Subscriptions Methods

Using the subscriptions methods of the Tableau Server REST API you can do the operations listed in the following category:

Subscriptions (scheduled e-mails to users of snapshots of a workbook's views)

List all subscriptions configured for a site or get the details of a specific subscription
Create a subscription to a workbook or view for a user and add it to a schedule
Update or delete a subscription for a user
Set or get the format of images delivered by a subscription
Suspend or resume a subscription

This functionality relates to the UI elements and concepts described at: Subscribe to Views(Link opens in a new window).

Create Subscription

Creates a new, unsuspended subscription to a view or workbook for a specific user on Tableau Server and Tableau Cloud. When a user is subscribed to the content, Tableau sends the content to the user in email on the schedule that you define.

For more information, see Subscribe to Views(Link opens in a new window) in the Tableau Server documentation.

Tableau Server and Tableau Cloud each have a different model for schedules and tasks. On Tableau Server, you create a schedule and add a task to it. On Tableau Cloud you create a task and define it's frequency. While the Create Subscription endpoint path and parameters are the same for both Server and Cloud, because the models are different, the request and response bodies are different.

Tableau Server Request
Tableau Cloud Request

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

URI

POST /api/api-version/sites/site-id/subscriptions

Parameter Values

api-version	The version of the API to use, such as `3.20`. For more information, see REST API and Resource Versions.
site-id	The ID of the site to create the subscription in.

JWT Access Scope

tableau:tasks:create (this scope is included in the scope: tableau:tasks)

This scope can be used to enable this REST method to be called from a connected app. For more information, see Tableau Cloud connected app scopes(Link opens in a new window). Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.

Tableau Server Request

Create a subscription task and add it to a server schedule on Tableau Server.
For Tableau Cloud, see Tableau Cloud Request.

Request Body

Copy

<tsRequest>
  <subscription
    subject="subscription-subject"
    attachImage="attach-image-flag"
    attachPdf="attach-pdf-flag"
    pageOrientation="page-orientation"
    pageSizeOption="page-size-option"    
    message="message">
      <content id="content-id"
        type="content-type"    
        sendIfViewEmpty="send-view-if-empty-flag"/>    
      <schedule id="schedule-id" />
      <user id="user-id" />
    </subscription>
</tsRequest>

Copy

{
  "subscription": {
    "subject": "subscription-subject",
    "attachImage": "attach-image-flag",
    "attachPdf": "attach-pdf-flag",
    "pageOrientation": "page-orientation",
    "pageSizeOption": "page-size-option",
    "message": "message",
    "content": {
      "id": "content-id",
      "type": "content-type",
      "sendIfViewEmpty": "send-view-if-empty-flag"
    },
    "schedule": {
      "id": "schedule-id"
    },
    "user": {
      "id": "user-id"
    }
  }
}

subscription-subject	A description for the subscription. This description is displayed when users list subscriptions for a site in the server environment. A description is required.
attach-image-flag	(Optional) Setting this `true` will cause the subscriber to receive mail with .png images of workbooks or views attached to it. This is the default behavior if neither `attachImage` or `attachPdf` are specified. If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets `attachImage` to `false` will cause an error.
attach-pdf-flag	(Optional) Setting this `true` will cause the subscriber to receive mail with a .pdf file containing images of workbooks or views attached to it. If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets `attachPdf` to `true` will cause an error.
page-orientation	(Optional) The orientation of the pages produced when attach-pdf-flag is `true`. The value can be `Portrait` or `Landscape`. If this parameter is not present the page orientation will default to `Portrait`.
page-size-option	(Optional) The type of page produced, which determines the page dimensions when attach-pdf-flag is `true`. The value can be: `A3`, `A4`, `A5`, `B5`, `Executive`, `Folio`, `Ledger`, `Legal`, `Letter`, `Note`, `Quarto`, or `Tabloid`. If this parameter is not present the page type will default to `Letter`.
message	The text body of the subscription email message.
content-type	`Workbook` to create a subscription for a workbook, or `View` to create a subscription for a view.
send-view-if-empty-flag	(Optional) Applies to views only. If `true`, an image is sent even if the view specified in a subscription is empty. If `false`, nothing is sent if the view is empty. The default value is true.
content-id	The ID of the workbook or view to subscribe to.
schedule-id	The ID of a schedule to associate the subscription with. To determine what schedules are available, call List Server Schedules. The type of the schedule must be `Subscription`.
user-id	The ID of the user to create the subscription for. Note: The user must have an email address defined in Tableau Server.

Permissions

The following list summarizes the permissions required to subscribe a user to specific content:

Tableau Server users who are server administrators can subscribe any user to any content.
Site administrators can subscribe any user on the site to any content on that site.
Project leaders can subscribe users to any content that they are project leaders for.
Content owners can subscribe users to any content they own.
Non-owners can subscribe themselves to any content that they have Read (view) permissions for.

Response Code

201

Response Body

Copy

<tsResponse>
  <subscription id="subscription-id"
    subject="subscription-subject"
    suspended="suspended-flag"
    pageOrientation="page-orientation"
    pageSizeOption="page-size-option" 
    message="message" >
      <content id="content-id"
        type="content-type" 
        sendIfViewEmpty="send-view-if-empty-flag"/>
      <schedule id="schedule-id" name="schedule-name" />
      <user id="user-id" name="user-name" />
  </subscription>
</tsResponse>

Copy

{
  "subscription": {
    "id": "subscription-id",
    "subject": "subscription-subject",
    "suspended": "suspended-flag",
    "pageOrientation": "page-orientation",
    "pageSizeOption": "page-size-option",
    "message": "message",
    "content": {
      "id": "content-id",
      "type": "content-type",
      "sendIfViewEmpty": "send-view-if-empty-flag"
    },
    "schedule": {
      "id": "schedule-id",
      "name": "schedule-name"
    },
    "user": {
      "id": "user-id",
      "name": "user-name"
    }
  }
}

Response Headers

Location: /api/3.20/sites/site-id/subscriptions/new-subscription-id

Version

Available in API 2.3 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400067	Invalid subscription subject	The subscription subject is null or empty.
400	400068	Invalid subscription target	The content type specified in the request body is not a workbook or view.
400	400069	Invalid subscription type	The subscription type is not `Workbook` or `View`.
400	400069	Invalid schedule type	The schedule type is not `Subscription`.
403	403060	No permissions to create subscription.	The user does not have permission to create a subscription for the specified content.
403	403063	No user permissions for content.	The user specified in the request body does not have Read (view) permissions for the specified content.
403	403064	No user email address.	The user does not have an email address.
404	404000	Site not found	The specified site doesn't correspond to an existing site.
404	404002	User not found	The user specified in the request body doesn't correspond to an existing user.
400	404006	Workbook not found	The workbook ID in the request body doesn't correspond to an existing workbook.
404	404011	View not found	The view ID in the request body doesn't correspond to an existing view.
404	404023	Schedule not found	The schedule ID in the request body doesn't correspond to an existing schedule.
405	405000	Invalid request method	Request type was not POST.

For more information, see Handling Errors.

Tableau Cloud Request

Create a subscription task and define its frequency on Tableau Cloud.
For Tableau Server, see Tableau Server Request.

Version: Available in API 3.20 (Tableau Cloud June 2023) and later. Not available for Tableau Server. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Administrators and any user with the creator or explorer role can create a custom schedule for a subscription task. Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:tasks:create Access Scopes Overview: Cloud(Link opens in a new window)

URI

POST /api/api-version/sites/site-luid/subscriptions

URI Parameter Values

api-version	The version of the API to use, such as `3.20`. For more information, see REST API and Resource Versions.
site-luid	The LUID for the site.

Request Body

Copy

<tsRequest>
  <subscription 
  subject="finance report" 
  attachImage="true" 
  attachPdf="true" 
  pageOrientation="true" 
  pageSizeOption="Folio" 
  message="Daily finance report"> 
    <content id="13237fd-6365-44d5-925b-644e5281b605"
      type="Workbook" 
      sendIfViewEmpty="false"/> 
    <user id="6t543fd-6365-44d5-925b-644e52897y65"/>
  </subscription>
  <schedule frequency="Daily">
    <frequencyDetails start="18:30:00" end="23:30:00">
      <intervals>
        <interval hours="4"/>
        <interval weekDay="Sunday"/>
        <interval WeekDay="Wednesday"/>
      </intervals>
    </frequencyDetails>
  </schedule>
</tsRequest>

Copy

{
  "subscription": {
    "subject": "finance report",
    "attachImage": "true",
    "attachPdf": "true",
    "pageOrientation": "true",
    "pageSizeOption": "Folio",
    "message": "daily finance report",
    "content": {
      "id": "13237fd-6365-44d5-925b-644e5281b605",
      "type": "Workbook",
      "sendIfViewEmpty": "false"
    },
    "user": {
      "id": "456"
    }
  },
  "schedule": {
    "frequency": "Daily",
    "frequencyDetails": {
      "start": "18:30:00",
      "end": "23:30:00",
      "intervals": {
        "interval": [
          { "hours": "4" },
          { "weekDay": "Sunday" },
          { "weekDay": "Wednesday" }
        ]
      }
    }
  }
}

Request Attributes

subject, contentId, and userId are required to create a custom schedule for a subscription, other attributes are optional with defaults. All attributes are optional when updating a custom schedule for a subscription.

subscription subject (Required to create subscription) string: A description for the subscription. This description is displayed when users list subscriptions for a site in the server environment.

subscription attachImage

boolean: Setting this true will cause the subscriber to receive mail with .png images of workbooks or views attached to it. This is the default behavior if neither attachImage or attachPdf are specified. Default is false.

If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets attachImage to false will cause an error.

subscription attachPdf

boolean: Setting this true will cause the subscriber to receive mail with a .pdf file containing images of workbooks or views attached to it. Default is false.

If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets attachPdf to true will cause an error.

subscription pageOrientation enumeration: The orientation of the pages produced when attach-pdf-flag is true. The value can be Portrait or Landscape. If this parameter is not present the page orientation will default to Portrait.

subscription pageSizeOption enumeration: The type of page produced, which determines the page dimensions when attach-pdf-flag is true. The value can be: A3, A4, A5, B5, Executive, Folio, Ledger, Legal, Letter, Note, Quarto, or Tabloid. If this parameter is not present the page type will default to Letter.

subscription message string: The text body of the subscription email message.

content id (Required to create subscription) LUID: The LUID of the workbook or view the user should be subscribed to.

content type (Required to create subscription) enumeration: Workbook to create a subscription for a workbook, or View to create a subscription for a view.

content sendIfViewEmpty boolean: Applies to views only. If true, an image is sent even if the view specified in a subscription is empty. If false, nothing is sent if the view is empty. The default value is true.

userId

(Required to create subscription) LUID: The LUID of the user to create the subscription for.

Note: The user must have an email address defined in Tableau Server.

schedule frequency

(Required to create subscription) enumeration: The scheduled frequency for triggering the extract refresh. Valid values include:

Hourly
Daily
Weekly
Monthly

frequencyDetails start (Required to create subscription) time: If the schedule frequency is Daily, Weekly, or Monthly, then start is the time of day on which scheduled jobs should run. If the frequency is Hourly, then start is the beginning of the time range during which jobs should be started. The valid format is HH:MM:SS.

frequencyDetails end

(Required to create subscription) time: If the schedule frequency is Hourly, or Daily with an interval of hours less than 24, then end is the time of day on which scheduled jobs should stop being run. The valid format is HH:MM:SS. Time should be specified in 5 minute increments and the difference between start and end times should be increments of 60 minutes. For example, a valid frequencyDetail would be:

<frequencyDetail start="20:45:00" end="21:45:00">
  . . . 
</frequencyDetail>
                                                

interval {interval type}

(Required to create subscription) string: Defines when and how often a scheduled job executes within the time parameters set in the start and end values of the frequencyDetails of the schedule. The type and valid values for an interval expression depend on the declared frequency of the schedule as follows:

Frequency	Valid interval values
`Hourly`	The value of an interval for an `Hourly` schedule can be only one of either: `hours=“1"` The number of hours between jobs. `1` is the only valid value. `minutes=“60"` The number of minutes between jobs. `60` is the only valid value. `weekDay=“weekday"` The weekday(s) the job will be run on. Valid values are: `Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday`. For example, to schedule to run a job every hour on Sunday and Wednesday, during the time range specified in `frequencyDetails` use an interval like: Copy `<intervals> <interval hours="1"/> <interval weekDay="Sunday"/> <interval weekDay="Wednesday"/> <intervals>`
`Daily`	The value of `Daily` can have multiple `weekday` elements, but only one `hours` declaration. An `hours` interval is required. `hours=“interval"` The interval between execution of jobs on the weekday(s) specified. Valid values are `2, 4, 6, 8, 12, or 24`. Note that if the `interval` value of a daily schedule is less than `24`, a `frequencyDetail end` time must be supplied. `weekDay=“weekday"` The weekday(s) the job will be run on. Valid values are: `Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday`. For example, to schedule to run a job every 4 hours on Sunday and Wednesday, during the time range specified in `frequencyDetails` use an interval like: Copy `<intervals> <interval hours="4"/> <interval weekDay="Sunday"/> <interval weekDay="Wednesday"/> <intervals>`
`Weekly`	`weekDay=“weekday"` The day of the week the schedule should run on. Multiple days can be specified for a Weekly schedule. Valid values are: `Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.`
`Monthly`	The day(s) of the month a job should be scheduled to run on. There are two ways to define a monthly interval: Specify the day(s) using the number of the day in the month; `monthDay=“day"` The number of the day of the month. Valid values are the whole numbers `1` to `31` or `LastDay`. If you specify `monthDay` by day number then you can use multiple `interval` instances to choose for the job to run on multiple days in the month. If you use `LastDay` then only one instance of `interval` can be used in the schedule to specify the last day of the month. Specify the day by describing which occurrence of a weekday within the month. `monthDay=“occurrence_of_weekday" Weekday=“weekday"` The occurrence of the specified weekday within the month when a job should be run. Valid values for `occurrencee_of_weekday` are `First, Second, Third, Fourth, Fifth, or LastDay`. Valid values for `weekday` are `Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday`. If the value is `lastDay` then the job will run on the last occurrence of the specified weekday in the month. For example, to make a schedule that that would run a job on the third Thursday of each month, you would use: Copy `<interval monthDay="Third" weekDay="Thursday"/>`

cURL Request Example

curl --location --request POST "qa-near.tsi.lan/api/3.20/sites/a946d998-2ead-4894-bb50-1054a91dcab3/tasks/subscription" - header "Content-Type: application/xml" --data "<tsRequest> <subscription subject="finance report" attachImage="true" attachPdf="true" pageOrientation="true" pageSizeOption="Folio" message="daily finance report"> <content id="13237fd-6365-44d5-925b-644e5281b605" type="Workbook" sendIfViewEmpty="false"/><user id="6t543fd-6365-44d5-925b-644e52897y65"/> </subscription> <schedule frequency='Daily'> <frequencyDetails start='18:30:00' end='23:00:00'> <intervals> <interval hours='4'/> <intervals> <interval weekDay='Sunday'/> <intervals> <interval weekDay='Wednesday'/> </intervals> </frequencyDetails> </schedule> </tsRequest>"

Response Code

200

Response Body

Copy

<tsResponse>
  <subscription
    id="45678fd-6365-44d5-925b-644e52834567"
    subject="finance report" 
    attachImage="true" 
    attachPdf="true" 
    pageOrientation="true" 
    pageSizeOption="Folio" 
    message="Daily finance report"> 
      <content 
        id="13237fd-6365-44d5-925b-644e5281b605"
        type="Workbook" 
        sendIfViewEmpty="false"/> 
      <user id="09876fd-6365-44d5-925b-644e528d5678"/>
  </subscription>
  <schedule id="54321fd-6365-44d5-925b-644e52812345"
    createdAt="2023-04-06T23:43:12-0700"
    updatedAt="2023-04-06T23:43:12-0700"
    frequency="Daily"
    nextRunAt="2023-04-06T23:43:12-0700" />
      <frequencyDetails start="18:30:00" end="23:30:00">
        <intervals>
          <interval hours="4"/>
          <interval weekDay="Sunday"/>
          <interval weekDay="Wednesday"/>
        </intervals>
      </frequencyDetails>
  </schedule>
</tsResponse>

Copy

{
  "subscription": {
    "id": "789",
    "subject": "finance report",
    "attachImage": "true",
    "attachPdf": "true",
    "pageOrientation": "true",
    "pageSizeOption": "Folio",
    "message": "Daily finance report",
    "content": {
      "id": "13237fd-6365-44d5-925b-644e5281b605",
      "type": "Workbook",
      "sendIfViewEmpty": "false"
    },
    "user": {
      "id": "09876fd-6365-44d5-925b-644e528d5678"
    }
  },
  "schedule": {
    "id": "54321fd-6365-44d5-925b-644e52812345",
    "createdAt": "2023-04-06T23:43:12-0700",
    "updatedAt": "2023-04-06T23:43:12-0700",
    "frequency": "Daily",
    "nextRunAt": "2023-04-06T23:43:12-0700",
    "frequencyDetails": {
      "start": "18:30:00",
      "end": "23:30:00",
      "intervals": {
        "interval": [
             { "hours": "4" },
          { "weekDay": "Sunday" },
          { "weekDay": "Wednesday" }
         ]
      }
    }
  }
}

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403004	Unauthorized Access	The user is not authorized to make this request..
404	404002	User not found	The user specified in the request could not be found.
404	404025	Subscription not found	The task for the subscription could not be found.
409	409004	invalid parameter value	The request is malformed or contains an invalid or missing schedule or interval parameter value. When the difference between `start` and `end` times are not increments of one hour, this error will result.

For more information, see Handling Errors.

Delete Subscription

Deletes the specified subscription on Tableau Server or Tableau Cloud.

URI

DELETE /api/api-version/sites/site-id/subscriptions/subscription-id

Parameter Values

api-version	The version of the API to use, such as `3.20`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the subscription.
subscription-id	The ID of the subscription to delete. To determine what subscriptions are available, call Query Subscriptions.

JWT Access Scope

tableau:tasks:delete (this scope is included in the scope: tableau:tasks)

Request Body

None

Permissions

Tableau Server users can call this method to delete any subscription that they had permission to create. For details, see Create Subscription.

Response Code

204

Response Body

None

Version

Version 2.3 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	`error` Code	Condition	Details
400	400062	Error deleting the subscription.	An unspecified error occured during the deletion operation.
401	401002	User not authenticated.	The user making the request has not been authenticated for this site.
403	403059	Delete forbidden.	A non-administrator user called this method but doesn't have permission to delete the subscription.
404	404000	Site not found	The specified site doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not DELETE.

For more information, see Handling Errors.

Get Subscription

Returns information about the specified subscription.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

URI

GET /api/api-version/sites/site-id/subscriptions/subscription-id

Parameter Values

api-version	The version of the API to use, such as `3.20`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the subscriptions.
subscription-id	The ID of the subscription to get information for.

JWT Access Scope

tableau:tasks:read (this scope is included in the scope: tableau:tasks)

Request Body

None

Permissions

Tableau Server administrators and all site administrators can get subscription information for users of projects within the scope of their administrative permissions. Other users can get subscription information only for their own subscriptions.

Curl Example

curl "http://MY-SERVER/api/3.20/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/subscriptions/59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Tableau Server and Tableau Cloud return different payloads in response to this request.

For Tableau Server: Server schedule is returned.

Response Code

200

Response Body

Tableau Server and Tableau Cloud return different payloads in response to this request.

Tableau Server Request

For Tableau Server, a subscription task with a server schedule is returned.

Copy

<tsResponse>
  <subscription id="subscription-id" 
    subject="subscription-subject"
    attachImage="attach-image-flag" attachPdf="attach-pdf-flag"
    suspended="suspended-flag"
    pageOrientation="page-orientation"
    pageSizeOption="page-size-option">
      <content id="content-id"
           type="content-type"
         sendIfViewEmpty="send-view-if-empty-flag"/>
      <schedule id="schedule-id" name="schedule-name" />
      <user id="user-id" name="user-name" />
   </subscription>
 </tsResponse>

Copy

{
  "subscription": {
    "id": "subscription-id",
    "subject": "subscription-subject",
    "attachImage": "attach-image-flag",
    "attachPdf": "attach-pdf-flag",
    "suspended": "suspended-flag",
    "pageOrientation": "page-orientation",
    "pageSizeOption": "page-size-option",
    "content": {
      "id": "content-id",
      "type": "content-type",
      "sendIfViewEmpty": "send-view-if-empty-flag"
    },
    "schedule": {
      "id": "schedule-id",
      "name": "schedule-name"
    },
    "user": {
      "id": "user-id",
      "name": "user-name"
    }
  }
}

Tableau Cloud Request

For Tableau Cloud, a subscription task with frequency is returned.

Copy

 <tsResponse>
  <subscription id="92cb4f51-7a15-41d4-bce4-a0fcce5fa985" subject="Subscription - postman" message="Test out postman Subscriptions" attachImage="true" attachPdf="false" suspended="false">
    <content id="be016ba6-d0a8-44ae-a057-b6df6931ccaa" type="Workbook" sendIfViewEmpty="true"/>
    <schedule frequency="Weekly" nextRunAt="2023-06-08T17:05:00-0700">
      <frequencyDetails start="17:05:00">
        <intervals>
          <interval weekDay="Thursday"/>
        </intervals>
      </frequencyDetails>
    </schedule>
    <user id="14064b01-7d58-4978-bdeb-a5f8d7694863" name="mysite.com"/>
  </subscription>
</tsResponse>

Copy

{
  "subscription": {
    "id": "92cb4f51-7a15-41d4-bce4-a0fcce5fa985",
    "subject": "Subscription - postman",
    "message": "Test out postman Subscriptions",
    "attachImage": "true",
    "attachPdf": "false",
    "suspended": "false",
    "content": {
      "id": "be016ba6-d0a8-44ae-a057-b6df6931ccaa",
      "type": "Workbook",
      "sendIfViewEmpty": "true"
    },
    "schedule": {
      "frequency": "Weekly",
      "nextRunAt": "2023-06-08T17:05:00-0700",
      "frequencyDetails": {
        "start": "17:05:00",
        "intervals": {
          "interval": [
            { "weekDay": "Thursday" }
          ]
        }
      }
    },
    "user": {
      "id": "14064b01-7d58-4978-bdeb-a5f8d7694863",
      "name": "gmysite.com"
    }
  }
}

Version

For Tableau Server: API 2.3 and later. For Tableau Cloud: API 3.20 (June 2023) and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	`error` Code	Condition	Details
403	403058	Unauthorized	The user attempted to get information for a subscription that they don't have permission to access.
404	404000	Site not found	The specified site doesn't correspond to an existing site.
404	404025	Subscription not found	The specified subscription doesn't correspond to an existing subscription.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

List Subscriptions

Returns a list of all the subscriptions on the specified site.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

URI

GET /api/api-version/sites/site-id/subscriptions

GET /api/api-version/sites/site-id/subscriptions?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version	The version of the API to use, such as `3.20`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the subscriptions.
page-size	(Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number	(Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

JWT Access Scope

tableau:tasks:read (this scope is included in the scope: tableau:tasks)

Request Body

None

Curl Example

curl "http://MY-SERVER/api/3.20/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/subscriptions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Permissions

Response Code

200

Response Body

Tableau Server and Tableau Cloud return different payloads in response to this request.

Tableau Server Request

For Tableau Server, a subscription task with a server schedule is returned.

Copy

<tsResponse>
   <pagination pageNumber="pageNumber"
    pageSize="page-size"
    totalAvailable="total-available"  />
   <subscriptions>
     <subscription id="subscription-id"
       subject="subscription-subject"
       attachImage="attach-image-flag"
       attachPdf="attach-pdf-flag"
       suspended="suspended-flag"
       pageOrientation="page-orientation"
       pageSizeOption="page-size-option" >
         <content id="content-id"
           type="content-type"
           sendIfViewEmpty="send-view-if-empty-flag"/>
         <schedule id="schedule-id" name="schedule-name"/>
         <user id="user-id" name="user-name" />
     </subscription>
     <!--   ... additional subscriptions ...   -->
   </subscriptions>
 </tsResponse>

Copy

{
  "pagination": {
    "pageNumber": "pageNumber",
    "pageSize": "page-size",
    "totalAvailable": "total-available"
  },
  "subscriptions": {
    "subscription": {
      "id": "subscription-id",
      "subject": "subscription-subject",
      "attachImage": "attach-image-flag",
      "attachPdf": "attach-pdf-flag",
      "suspended": "suspended-flag",
      "pageOrientation": "page-orientation",
      "pageSizeOption": "page-size-option",
      "content": {
        "id": "content-id",
        "type": "content-type",
        "sendIfViewEmpty": "send-view-if-empty-flag"
      },
      "schedule": {
        "id": "schedule-id",
        "name": "schedule-name"
      },
      "user": {
        "id": "user-id",
        "name": "user-name"
      }
    }
  }
}

Tableau Cloud Request

For Tableau Cloud, a task with frequency is returned.

Copy

<tsResponse>
  <pagination pageNumber="1" pageSize="100" totalAvailable="1"/>
  <subscriptions>
    <subscription id="92cb4f51-7a15-41d4-bce4-a0fcce5fa985" 
      subject="Subscription - postman" 
      message="weekly report" 
      attachImage="true" 
      attachPdf="false" 
      suspended="false">
        <content id="be016ba6-d0a8-44ae-a057-b6df6931ccaa" 
          type="Workbook" sendIfViewEmpty="true"/>
            <schedule frequency="Weekly" 
              nextRunAt="2023-06-08T17:05:00-0700">
                <frequencyDetails start="17:05:00">
                  <intervals>
                    <interval weekDay="Thursday"/>
                  </intervals>
                </frequencyDetails>
              </schedule>
              <user id="14064b01-7d58-4978-bdeb-a5f8d7694863" 
                name="me@mysite.com"/>
    </subscription>
  </subscriptions>
</tsResponse>

Copy

{
  "pagination": {
    "pageNumber": "1",
    "pageSize": "100",
    "totalAvailable": "1"
  },
  "subscriptions": {
    "subscription": {
      "id": "92cb4f51-7a15-41d4-bce4-a0fcce5fa985",
      "subject": "Subscription - postman",
      "message": "weekly report",
      "attachImage": "true",
      "attachPdf": "false",
      "suspended": "false",
      "content": {
        "id": "be016ba6-d0a8-44ae-a057-b6df6931ccaa",
        "type": "Workbook",
        "sendIfViewEmpty": "true"
      },
      "schedule": {
        "frequency": "Weekly",
        "nextRunAt": "2023-06-08T17:05:00-0700",
        "frequencyDetails": {
          "start": "17:05:00",
          "intervals": {
            "interval": [
              { "weekDay": "Thursday" }
            ]
          }
        }
      },
      "user": {
        "id": "14064b01-7d58-4978-bdeb-a5f8d7694863",
        "name": "memysite.com"
      }
    }
  }
}

Version

For Tableau Server: API 2.3 and later. For Tableau Cloud: API 3.20 (June 2023) and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	`error` Code	Condition	Details
400	400006	Invalid page number	The page number parameter is not an integer, is less than one, or is greater than the final page number for the sites at the requested page size.
400	400007	Invalid page size	The page size parameter is not an integer, or is less than one.
403	403014	Page size limit exceeded	The specified page size is larger than the maximum page size.
404	404000	Site not found	The specified site doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Update Subscription

Modifies an existing subscription on Tableau Server. You can change the subject, server schedule, and suspension state for the subscription.

Tableau Server Requests
Tableau Cloud Request

URI

PUT /api/api-version/sites/site-id/subscriptions/subscription-id

Parameter Values

api-version	The version of the API to use, such as `3.20`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the workbook.
subscription-id	The ID of the subscription to update.

JWT Access Scope

tableau:tasks:update (this scope is included in the scope: tableau:tasks)

Tableau Server Request

Update the attributes of a subscription task on a server schedule on Tableau Server.
For Tableau Cloud, see Tableau Cloud Request.

Copy

<tsRequest>
  <subscription
    subject="subscription-subject"
    attachImage="attach-image-flag"
    attachPdf="attach-pdf-flag"
    pageOrientation="page-orientation"
    pageSizeOption="page-size-option"
    suspended="suspended-flag">
      <schedule id="new-schedule-id"
      <content sendIfViewEmpty="send-view-if-empty-flag" />
  </subscription>
</tsRequest>

Copy

{
  "subscription": {
    "subject": "subscription-subject",
    "attachImage": "attach-image-flag",
    "attachPdf": "attach-pdf-flag",
    "pageOrientation": "page-orientation",
    "pageSizeOption": "page-size-option",
    "suspended": "suspended-flag",
    "schedule": {
      "id": "new-schedule-id"
    },
    "content": {
      "sendIfViewEmpty": "send-view-if-empty-flag"
    }
  }
}

Attribute Values

new-subscription-subject	(Optional) A new subject for the subscription.
attach-image-flag	(Optional) Setting this `true` will cause the subscriber to receive mail with .png images of workbooks or views attached to it. This is the default behavior if neither `attachImage` or `attachPdf` are specified. If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets `attachImage` to `false` will cause an error.
attach-pdf-flag	(Optional) Setting this `true` will cause the subscriber to receive mail with a .pdf file containing images of workbooks or views attached to it. If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets `attachPdf` to `true` will cause an error.
page-orientation	(Optional) The orientation of the pages produced when attach-pdf-flag is `true`. The value can be `Portrait` or `Landscape`. If this parameter is not present the page orientation will default to `Portrait`.
page-size-option	(Optional) The type of page produced, which determines the page dimensions when attach-pdf-flag is `true`. The value can be: `A3`, `A4`, `A5`, `B5`, `Executive`, `Folio`, `Ledger`, `Legal`, `Letter`, `Note`, `Quarto`, or `Tabloid`. If this parameter is not present the page type will default to `Letter`.
suspended-flag	(Optional boolean) Setting `suspended` to `true` stops email delivery for the specified subscription. Setting it to `false` will resume email delivery for the subscription.
new-schedule-id	(Optional) The ID of a server schedule to associate this subscription with. To determine what schedules are available, call List Server Schedules. The type of the schedule must be `Subscription`.
send-view-if-empty-flag	(Optional) Applies to views only. If `true`, an image is sent even if the view specified in a subscription is empty. If `false`, nothing is sent if the view is empty. The default value is true.

Permissions

Tableau Server users can call this method to update any subscription that they have permission to create. For details, see Create Server Subscription.

Response Code

200

Response Body

XML

Copy

<tsResponse>
  <subscription id="subscription-id"
    subject="subscription-subject"
    suspended="suspended-flag"    
    pageOrientation="page-orientation"
    pageSizeOption="page-size-option" >
      <content id="content-id"
        type="content-type"
        sendIfViewEmpty="send-view-if-empty-flag"/>
      <schedule id="schedule-id" name="schedule-name" />
      <user id="user-id" name="user-name" />
  </subscription>
</tsResponse>

JSON

Copy

{
  "subscription": {
    "id": "subscription-id",
    "subject": "subscription-subject",
    "suspended": "suspended-flag",
    "pageOrientation": "page-orientation",
    "pageSizeOption": "page-size-option",
    "content": {
      "id": "content-id",
      "type": "content-type",
      "sendIfViewEmpty": "send-view-if-empty-flag"
    },
    "schedule": {
      "id": "schedule-id",
      "name": "schedule-name"
    },
    "user": {
      "id": "user-id",
      "name": "user-name"
    }
  }
}

Version

Version 2.3 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400067	Invalid subscription subject	The subscription subject is null or empty.
400	400069	Invalid subscription type	The subscription type is not `Workbook` or `View`.
400	400069	Invalid schedule type	The schedule type is not `Subscription`.
400	400133	Invalid data condition type	The data condition type is invalid for the subscription.
403	403065	No permissions to update subscription.	The user does not have permission to update the specified subscription.
404	404000	Site not found	The specified site doesn't correspond to an existing site.
404	404023	Schedule not found	The schedule ID in the request body doesn't correspond to an existing schedule.
405	405000	Invalid request method	Request type was not PUT.

For more information, see Handling Errors.

Tableau Cloud Request

Update the attributes of a subscription task and its frequency on Tableau Cloud.
For Tableau Server, see Tableau Server Request.

Version: Available in API 3.20 (Tableau Cloud June 2023) and later. Not available for Tableau Server. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Administrators and any user with the creator role can create a custom schedule for a subscription task. Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:tasks:update Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

PUT /api/api-version/sites/site-luid/subscriptions/task-luid

URI Parameter Values

api-version	The version of the API to use, such as `3.20`. For more information, see REST API and Resource Versions.
site-luid	The LUID for the site.
task-luid	The LUID of the extract refresh task. Use Query subscriptions to find task IDs by subscription subject or user.

Request Body

Copy

<tsRequest>
  <subscription 
  subject="finance report" 
  attachImage="true" 
  attachPdf="true" 
  pageOrientation="true" 
  pageSizeOption="Folio" 
  message="Daily finance report"> 
    <content id="13237fd-6365-44d5-925b-644e5281b605"
      type="Workbook" 
      sendIfViewEmpty="false"/> 
    <user id="6t543fd-6365-44d5-925b-644e52897y65"/>
  </subscription>
  <schedule frequency="Daily">
    <frequencyDetails start="18:30:00" end="23:30:00">
      <intervals>
        <interval hours="4"/>
        <interval weekDay="Sunday"/>
        <interval weekDay="Wednesday"/>
      </intervals>
    </frequencyDetails>
  </schedule>
</tsRequest>

Copy

{
  "subscription": {
    "subject": "finance report",
    "attachImage": "true",
    "attachPdf": "true",
    "pageOrientation": "true",
    "pageSizeOption": "Folio",
    "message": "daily finance report",
    "content": {
      "id": "13237fd-6365-44d5-925b-644e5281b605",
      "type": "Workbook",
      "sendIfViewEmpty": "false"
    },
    "user": {
      "id": "456"
    }
  },
  "schedule": {
    "frequency": "Daily",
    "frequencyDetails": {
      "start": "18:30:00",
      "end": "23:30:00",
      "intervals": {
        "interval": [
          { "hours": "4" },
          { "weekDay": "Sunday" },
          { "weekDay": "Wednesday" }
        ]

      }
    }
  }
}

Request Attributes

subject, contentId, userId and all schedule attributes are required to create a custom schedule for a subscription, other attributes are optional with defaults. All attributes are optional when updating a custom schedule for a subscription.

subscription attachImage

If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets attachImage to false will cause an error.

subscription attachPdf

boolean: Setting this true will cause the subscriber to receive mail with a .pdf file containing images of workbooks or views attached to it. Default is false.

If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets attachPdf to true will cause an error.

subscription message string: The text body of the subscription email message.

content id (Required to create subscription) LUID: The LUID of the workbook or view the user should be subscribed to.

content type (Required to create subscription) enumeration: Workbook to create a subscription for a workbook, or View to create a subscription for a view.

userId

(Required to create subscription) LUID: The LUID of the user to create the subscription for.

Note: The user must have an email address defined in Tableau Server.

schedule frequency

(Required to create subscription) enumeration: The scheduled frequency for triggering the extract refresh. Valid values include:

Hourly
Daily
Weekly
Monthly

frequencyDetails end

<frequencyDetail start="20:45:00" end="21:45:00">
  . . . 
</frequencyDetail>
                                                

interval {interval type}

Frequency	Valid interval values
`Hourly`	The value of an interval for an `Hourly` schedule can be only one of either: `hours=“1"` The number of hours between jobs. `1` is the only valid value. `minutes=“60"` The number of minutes between jobs. `60` is the only valid value. `weekDay=“weekday"` The weekday(s) the job will be run on. Valid values are: `Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday`. For example, to schedule to run a job every hour on Sunday and Wednesday, during the time range specified in `frequencyDetails` use an interval like: Copy `<intervals> <interval hours="1"/> <interval weekDay="Sunday"/> <interval weekDay="Wednesday"/> <intervals>`
`Daily`	The value of `Daily` can have multiple `weekday` elements, but only one `hours` declaration. An `hours` interval is required. `hours=“interval"` The interval between execution of jobs on the weekday(s) specified. Valid values are `2, 4, 6, 8, 12, or 24`. Note that if the `interval` value of a daily schedule is less than `24`, a `frequencyDetail end` time must be supplied. `weekDay=“weekday"` The weekday(s) the job will be run on. Valid values are: `Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday`. For example, to schedule to run a job every 4 hours on Sunday and Wednesday, during the time range specified in `frequencyDetails` use an interval like: Copy `<intervals> <interval hours="4"/> <interval weekDay="Sunday"/> <interval weekDay="Wednesday"/> <intervals>`
`Weekly`	`weekDay=“weekday"` The day of the week the schedule should run on. Multiple days can be specified for a Weekly schedule. Valid values are: `Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.`
`Monthly`	The day(s) of the month a job should be scheduled to run on. There are two ways to define a monthly interval: Specify the day(s) using the number of the day in the month; `monthDay=“day"` The number of the day of the month. Valid values are the whole numbers `1` to `31` or `LastDay`. If you specify `monthDay` by day number then you can use multiple `interval` instances to choose for the job to run on multiple days in the month. If you use `LastDay` then only one instance of `interval` can be used in the schedule to specify the last day of the month. Specify the day by describing which occurrence of a weekday within the month. `monthDay=“occurrence_of_weekday" Weekday=“weekday"` The occurrence of the specified weekday within the month when a job should be run. Valid values for `occurrencee_of_weekday` are `First, Second, Third, Fourth, Fifth, or LastDay`. Valid values for `weekday` are `Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday`. If the value is `lastDay` then the job will run on the last occurrence of the specified weekday in the month. For example, to make a schedule that that would run a job on the third Thursday of each month, you would use: Copy `<interval monthDay="Third" weekDay="Thursday"/>`

cURL Request Example

curl --location --request PUT "qa-near.tsi.lan/api/3.20/sites/a946d998-2ead-4894-bb50-1054a91dcab3/subscriptions/r2345998-2ead-4894-bb50-1054a9109876" --header "Content-Type: application/xml" --data "<tsRequest> > <subscription subject="finance report" attachImage="true" attachPdf="true" pageOrientation="true" pageSizeOption="Folio" message="daily finance report"> <content id="13237fd-6365-44d5-925b-644e5281b605" type="Workbook" sendIfViewEmpty="false"/><user id="6t543fd-6365-44d5-925b-644e52897y65"/> </subscription> <schedule frequency='Daily'> <frequencyDetails start='18:30:00' end='23:00:00'> <intervals> <interval hours='4'/> <interval weekDay='Sunday'/> <interval weekDay='Wednesday'/> </intervals> </frequencyDetails> </schedule> </tsRequest>"

Response Code

200

Response Body

Copy

<tsResponse>
  <subscription
    id="45678fd-6365-44d5-925b-644e52834567"
    subject="finance report" 
    attachImage="true" 
    attachPdf="true" 
    pageOrientation="true" 
    pageSizeOption="Folio" 
    message="daily finance report"> 
      <content 
        id="13237fd-6365-44d5-925b-644e5281b605"
        type="Workbook" 
        sendIfViewEmpty="false"/> 
      <user id="09876fd-6365-44d5-925b-644e528d5678"/>
  </subscription>
  <schedule id="54321fd-6365-44d5-925b-644e52812345"
    createdAt="2023-04-06T23:43:12-0700"
    updatedAt="2023-04-06T23:43:12-0700"
    frequency="Daily"
    nextRunAt="2023-04-06T23:43:12-0700" />
      <frequencyDetails start="18:30:00" end="23:30:00">
        <intervals>
          <interval hours="4"/>
          <interval weekDay="Sunday"/>
          <interval weekDay="Wednesday"/>
        </intervals>
      </frequencyDetails>
  </schedule>
</tsResponse>

Copy

{
  "subscription": {
    "id": "789",
    "subject": "finance report",
    "attachImage": "true",
    "attachPdf": "true",
    "pageOrientation": "true",
    "pageSizeOption": "Folio",
    "message": "daily finance report",
    "content": {
      "id": "13237fd-6365-44d5-925b-644e5281b605",
      "type": "Workbook",
      "sendIfViewEmpty": "false"
    },
    "user": {
      "id": "09876fd-6365-44d5-925b-644e528d5678"
    }
  },
  "schedule": {
    "id": "54321fd-6365-44d5-925b-644e52812345",
    "createdAt": "2023-04-06T23:43:12-0700",
    "updatedAt": "2023-04-06T23:43:12-0700",
    "frequency": "Daily",
    "nextRunAt": "2023-04-06T23:43:12-0700",
    "frequencyDetails": {
      "start": "18:30:00",
      "end": "23:30:00",
      "intervals": {
        "interval": [
          { "hours": "4" },
          { "weekDay": "Sunday" },
          { "weekDay": "Wednesday" }
        ]
      }
    }
  }
}

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403004	Unauthorized Access	The user is not authorized to make this request.
404	404002	User not found	The user specified in the request could not be found.
404	404025	Subscription not found	The task for the subscription could not be found.
409	409004	invalid parameter value	The request is malformed or contains an invalid or missing schedule or interval parameter value. When the difference between `start` and `end` times are not increments of one hour, this error will result.

For more information, see Handling Errors.

Thanks for your feedback!

Tableau REST API Help

Subscriptions Methods

Create Subscription

URI

Parameter Values

JWT Access Scope

Tableau Server Request

Request Body

Permissions

Response Code

Response Body

Response Headers

Version

Errors

Tableau Cloud Request

URI

URI Parameter Values

Request Body

Request Attributes

cURL Request Example

Response Code

Response Body

Errors

Delete Subscription

URI

Parameter Values

JWT Access Scope

Request Body

Permissions

Response Code

Response Body

Version

Errors

Get Subscription

URI

Parameter Values

JWT Access Scope

Request Body

Permissions

Curl Example

Response Code

Response Body

Tableau Server Request

Tableau Cloud Request

Version

Errors

List Subscriptions

URI

Parameter Values

JWT Access Scope

Request Body

Curl Example

Permissions

Response Code

Response Body

Tableau Server Request

Tableau Cloud Request

Version

Errors

Update Subscription

URI

Parameter Values

JWT Access Scope

Tableau Server Request

Attribute Values

Permissions

Response Code

Response Body

XML

JSON

Version

Errors

Tableau Cloud Request

URI

URI Parameter Values

Request Body

Request Attributes

cURL Request Example

Response Code

Response Body