Data-Driven Alerts Methods

Using the data-driven alerts methods of the Tableau Server REST API you can:

  • List, update, or delete the data-driven alerts of a site
  • Get the details of a specific data-driven alert
  • Add or delete the users of a specific data-driven alert

This functionality relates to the UI elements and concepts described at: Set Up for Data-Driven Alerts(Link opens in a new window).

Add User to Data-Driven Alert

Adds a specified user to the recipients list for a data-driven alert.

URI

POST /api/api-version/sites/site-id/dataAlerts/data-alert-id/users

Parameter Values

api-version The version of the API to use, such as 3.12. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the specified data-driven alert.
data-alert-id The ID of the data-driven alert. You can obtain this ID by calling Query Data-Driven Alerts.

Request Body

<tsRequest>
  <user id="user-id"/>
</tsRequest>
        

Permissions

This method can only be called by server administrators and site administrators, and by users who are owners of the specified alert.

Response Code

200

Response Body

<tsResponse>
  <user id="user-id"
    name="user-name"
    siteRole="site-role"
    externalAuthUserId="external-user-id"/>
</tsResponse>
        

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Write forbidden A user called this method who does not have the required permissions.
403 409028 Adding recipient to data-driven alert forbidden The user is not authorized to add the recipient to the data-driven alert.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404002 Resource Not Found The user ID specified in the request body is invalid.
404 409023 Resource Not Found The data-driven alert ID specified in the URI is invalid.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.12/sites/13020592-762f-4de4-a25e-f4beb005836e/dataAlerts/e5a4b73e-5cbb-412d-907e-f31cc31684f7/users" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-user-to-alert.xml

Content of add-user-to-alert.xml:

<tsRequest>
  <user id="8eda27d9-5ad2-42cd-a39a-61bc01a423af"/>
</tsRequest>

Example response:


<tsResponse>
  <user id="8eda27d9-5ad2-42cd-a39a-61bc01a423af"
        name="admin"
        siteRole="ServerAdministrator"
        externalAuthUserId=""/>
</tsresponse>

Delete Data-Driven Alert

Deletes the specified data-driven alert from the specified site.

URI

DELETE /api/api-version/sites/site-id/dataAlerts/data-alert-id

Parameter Values

api-version The version of the API to use, such as 3.12. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the specified data-driven alert.
data-alert-id The ID of the data-driven alert. You can obtain this ID by calling Query Data-Driven Alerts.

Request Body

None

Permissions

This method can only be called by server and site administrators, and by users who are owners or recipients of the specified data-driven alert.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Delete forbidden A user called this method who does not have the required permissions
404 409023 Resource Not Found The data-driven alert ID specified in the URI is invalid.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.12/sites/13020592-762f-4de4-a25e-f4beb005836e/dataAlerts/e5a4b73e-5cbb-412d-907e-f31cc31684f7" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Delete User from Data-Driven Alert

Removes a specified user from the recipients list for a data-driven alert.

URI

DELETE /api/api-version/sites/site-id/dataAlerts/data-alert-id/users/user-id

Parameter Values

api-version The version of the API to use, such as 3.12. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the specified data-driven alert.
data-alert-id The ID of the data-driven alert. You can obtain this ID by calling Query Data-Driven Alerts.
user-id The ID (not name) of the user to remove from the data-driven alert.

Request Body

None

Permissions

This method can only be called by server and site administrators, and by users who are owners of the specified data-driven alert.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Delete forbidden A user called this method who does not have the required permissions.
403 409029 Deleting recipient from data-driven alert forbidden The user is not authorized to remove the recipient from the data-driven alert.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404002 Resource Not Found The user ID specified in the request body is invalid.
404 409023 Resource Not Found The data-driven alert ID specified in the URI is invalid.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.12/sites/13020592-762f-4de4-a25e-f4beb005836e/dataAlerts/e5a4b73e-5cbb-412d-907e-f31cc31684f7/users/ff43cb47-f208-4d2f-9a22-0fbb6d29f7f1" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Query Data-Driven Alerts

Returns a list of data-driven alerts in use on the specified site.

URI

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

URI

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

URI

GET /api/api-version/sites/site-id/dataAlerts?filter=viewId:eq:view-luid

Parameter Values

api-version The version of the API to use, such as 3.12. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains data-driven alerts.

Request Body

None

Permissions

This method can only be called by server and site administrators, and by users who are owners or recipients for one or more alerts. Server administrators will see alerts for all sites on the server.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="1" pageSize="100" totalAvailable="1"/>
  <dataAlerts>
    <dataAlert id="alert-id" subject="alert-subject" creatorId="creator-id" createdAt="created-date" updatedAt="updated-date" frequency="alert-frequency" public="is-public-flag">
      <owner id="owner-id" name="username"/>
      <view id="view-id" name="view-name">
        <workbook id="workbook-id" name="workbook-name"/>
        <project id="project-id" name="project-name"/>
      </view>
    </dataAlert>
  </dataAlerts>
</tsResponse>
        

The createdAt and updatedAt values are dates and times in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

Version 3.2 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 403004 Read forbidden A user queried this method who does not have the required permissions
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
404 404000 Site not found The site ID or URL namespace in the URI 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.12/sites/13020592-762f-4de4-a25e-f4beb005836e/dataAlerts" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse>
  <dataAlerts>
    <dataAlert id="e5a4b73e-5cbb-412d-907e-f31cc31684f7" subject="Data alert - Shipping" creatorId="8eda27d9-5ad2-42cd-a39a-61bc01a423af" createdAt="2018-08-13T20:55:29Z" updatedAt="2018-08-21T00:05:34Z" frequency="daily" public="true">
      <owner id="8eda27d9-5ad2-42cd-a39a-61bc01a423af" name="admin"/>
      <view id="defbf126-5e8b-4c12-9c55-6e772c91bf62" name="Shipping">
        <workbook id="4c384398-085c-4236-91a0-4f92bee1c9ba" name="Superstore"/>
        <project id="291de556-9f2b-11e8-a25f-631b5eb7ad77" name="Default"/>
      </view>
    </dataAlert>
  </dataAlerts>
</tsResponse>

Query Data-Driven Alert Details

Returns details on a specified data-driven alert, including the recipients of the alert.

URI

GET /api/api-version/sites/site-id/dataAlerts/data-alert-id

Parameter Values

api-version The version of the API to use, such as 3.12. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the specified data-driven alert.
data-alert-id The ID of the data-driven alert. You can obtain this ID by calling Query Data-Driven Alerts.

Request Body

None

Permissions

This method can only be called by server and site administrators, and by users who are owners or recipients of the specified alert.

Response Code

200

Response Body

<tsResponse>
  <dataAlert id="alert-id" subject="alert-subject" creatorId="creator-id" createdAt="created-date" updatedAt="updated-date" frequency="alert-frequency" public="is-public-flag">
    <owner id="owner-id" name="username"/>
      <view id="view-id" name="view-name">
        <workbook id="workbook-id" name="workbook-name"/>
        <project id="project-id" name="project-name"/>
      </view>
      <recipients>
        <recipient id="recipient-id"/>
      </recipients>
  </dataAlert>
</tsResponse>
        

The createdAt and updatedAt values are dates and times in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Read forbidden A user queried this method who does not have the required permissions
404 409023 Resource Not Found The data-driven alert ID specified in the URI is invalid.
404 404000 Site not found The site ID or URL namespace in the URI 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.12/sites/13020592-762f-4de4-a25e-f4beb005836e/dataAlerts/e5a4b73e-5cbb-412d-907e-f31cc31684f7" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse>
  <dataAlert id="e5a4b73e-5cbb-412d-907e-f31cc31684f7" subject="Data alert - Shipping" creatorId="8eda27d9-5ad2-42cd-a39a-61bc01a423af" createdAt="2018-08-13T20:55:29Z" updatedAt="2018-08-21T00:05:34Z" frequency="daily" public="true">
    <owner id="8eda27d9-5ad2-42cd-a39a-61bc01a423af" name="admin"/>
    <view id="defbf126-5e8b-4c12-9c55-6e772c91bf62" name="Shipping">
      <workbook id="4c384398-085c-4236-91a0-4f92bee1c9ba" name="Superstore"/>
      <project id="291de556-9f2b-11e8-a25f-631b5eb7ad77" name="Default"/>
    </view>
    <recipients>
      <recipient id="4"/>
    </recipients>
  </dataAlert>
</tsResponse>

Update Data-Driven Alert

Update one or more settings for the specified data-driven alert; including the alert subject, frequency, and owner.

URI

PUT /api/api-version/sites/site-id/dataAlerts/data-alert-id

Parameter Values

api-version The version of the API to use, such as 3.12. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data-driven alert.
data-alert-id The ID of the data-driven alert. You can obtain this ID by calling Query Data-Driven Alerts.

Request Body

<tsRequest>
    <dataAlert subject="data-alert-subject"
        frequency="data-alert-frequency" public="is-public-flag">
            <owner id="data-alert-owner-id"/>
    </dataAlert>
 </tsRequest>
        

Attribute Values

data-alert-subject (Optional) The string to set as the new subject of the alert.
data-alert-frequency (Optional) The frequency of the data-driven alert: once, frequently, hourly, daily, or weekly.
data-alert-owner-id (Optional) The ID of the user to assign as owner of the data-driven alert.
is-public-flag (Optional) Determines the visibility of the data-driven alert. If the flag is true, users with access to the view containing the alert can see the alert and add themselves as recipients. If the flag is false, then the alert is only visible to the owner, site or server administrators, and specific users they add as recipients. (Optional) Determines the visibility of the data-driven alert. If the flag is true, users with access to the view containing the alert can see the alert and add themselves as recipients. If the flag is false, then the alert is only visible to the owner, site or server administrators, and specific users they add as recipients.

Permissions

This method can only be called by server and site administrators, and by users who are owners of the specified alert.

Response Code

200

Response Body

<tsResponse>
  <dataAlert id="data-alert-id" subject="data-alert-subject" creatorId="user-id"
    createdAt="created-date" updatedAt="updated-date" frequency="data-alert-frequency" public="is-public-flag">
    <owner id="user-id" name="user-name" />
    <view id="view-id" name="view-name" >
      <workbook id="workbook-id" name="workbook-name" />
      <project id="project-id" name="project-name" />
    </view>
  </dataAlert>
</tsResponse>
        

The createdAt and updatedAt attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Write forbidden A user called this method who does not have the required permissions.
403 409030 Updating data-driven alert forbidden The user is not authorized to update the data-driven alert.
404 409023 Resource Not Found The data-driven alert ID specified in the URI is invalid.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404002 Resource Not Found The user ID specified in the request body is invalid.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.12/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/dataAlerts/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @update-alert.xml

Content of update-alert.xml:

<tsRequest>
    <dataAlert subject="Data alert - Shipping" frequency="daily" public="true">
        <owner id="8eda27d9-5ad2-42cd-a39a-61bc01a423af"/>
    </dataAlert>
</tsRequest>

Example response:

<tsResponse>
  <dataAlert id="c60bbd4e-dd98-469f-bf71-83c42378f427" subject="Data alert - Shipping"
    creatorId="8eda27d9-5ad2-42cd-a39a-61bc01a423af" createdAt="2018-08-22T23:16:41Z"
    updatedAt="2018-08-24T20:27:14Z" frequency="daily" public="true">
    <owner id="8eda27d9-5ad2-42cd-a39a-61bc01a423af" name="admin"/>
    <view id="defbf126-5e8b-4c12-9c55-6e772c91bf62" name="Shipping">
      <workbook id="4c384398-085c-4236-91a0-4f92bee1c9ba" name="Superstore"/>
      <project id="291de556-9f2b-11e8-a25f-631b5eb7ad77" name="Default"/>
    </view>
  </dataAlert>
</tsResponse>


Thanks for your feedback!