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. When a user is subscribed to the content, Tableau Server sends the content to the user in email on the schedule that's defined in Tableau Server and specified in this call.
For more information, see Subscribe to Views(Link opens in a new window) in the Tableau Server documentation.
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.18 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site to create the subscription in. |
Request Body
<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>
Attribute Values
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 If subscriptions to attachments are disabled in Tableau server or site settings,
then making a request that sets |
attach-pdf-flag |
(Optional) Setting this If subscriptions to attachments are disabled in Tableau server or site settings,
then making a request that sets |
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 Query 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
<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" />
<schedule id="schedule-id" name="schedule-name" />
<user id="user-id" name="user-name" />
</subscription>
</tsResponse>
Response Headers
Location: /api/3.18/sites/site-id/subscriptions/new-subscription-id
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 | 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.
Delete Subscription
Deletes the specified subscription.
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.18 . 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. |
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.
Query 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.18 . 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. |
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.
Response Code
200
Response Body
<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>
Version
Version 2.3 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.
Example
curl "http://MY-SERVER/api/3.18/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/subscriptions/59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse version-and-namespace-settings>
<subscription id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" subject="Daily Statistics"
attachImage="false" attachPdf="true" "suspended="false"
pageOrientation="Landscape"
pageSizeOption="A4" >
<content id="08b50973-a526-4f65-b898-829e6292c949" type="View" sendIfViewEmpty="true"/>
<schedule id="67e341a3-7c58-4605-9897-7db1e565e827" name="Mondays" />
<user id="c6f87a48-f603-41dc-af0c-8098c763df97" name="joe@example.com" />
</subscription>
</tsResponse>
Query 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.18 . 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. |
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.
Response Code
200
Response Body
<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>
Version
Version 2.3 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.
Example
curl "http://MY-SERVER/api/3.18/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/subscriptions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse version-and-namespace-settings>
<pagination pageNumber="1" pageSize="100" totalAvailable="2"/>
<subscriptions>
<subscription id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" subject="Daily Statistics"
attachImage="false" attachPdf="true" suspended="false"
pageOrientation="Lanscape" pageSizeOption="A4" >
<content id="08b50973-a526-4f65-b898-829e6292c949" type="View" sendIfViewEmpty="true"/>
<schedule id="67e341a3-7c58-4605-9897-7db1e565e827" name="Mondays" />
<user id="c6f87a48-f603-41dc-af0c-8098c763df97" name="joe@example.com" />
</subscription>
<subscription id="672930ac-b7d2-4ed9-beb7-d931241f8209" subject="Sales Update" "suspended="true""
pageOrientation="Portrait" pageSizeOption="Letter" >
<content id="8fcd394e-27f4-4071-9c5a-2dfed2ad1230" type="View" />
<schedule id="67e341a3-7c58-4605-9897-7db1e565e827" name="Weekly Updates" />
<user id="e54cde3c-0c44-4024-a34e-8cab98f58ea2" name="Michelle@example.com" />
</subscription>
</subscriptions>
</tsResponse>
Update Subscription
Modifies an existing subscription, allowing you to change the subject, schedule, and suspension state for the subscription.
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.18 . 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. |
Request Body
<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>
Attribute Values
new-subscription-subject | (Optional) A new subject for the subscription. |
attach-image-flag |
(Optional) Setting this If subscriptions to attachments are disabled in Tableau server or site settings,
then making a request that sets |
attach-pdf-flag |
(Optional) Setting this If subscriptions to attachments are disabled in Tableau server or site settings,
then making a request that sets |
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 schedule to associate this subscription with. To determine what schedules are available,
call Query 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 Subscription.
Response Code
200
Response Body
<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>
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.