Skip to main content

Subscription

View as Markdown

Subscription object​

A subscription registers a workspace user or a notification destination as a subscriber of a dashboard schedule. Each time the schedule runs, the subscriber receives a snapshot of the published dashboard, unless the subscription is refresh-only. See Manage scheduled dashboard updates and subscriptions.

subscription_idstringOutput only

UUID identifying the subscription.

Example: 01ee9e6f2a2c1a8d9273d3c3e852fc2b

schedule_idstringOutput only

UUID identifying the schedule to which the subscription belongs.

Example: 01ef0cb45e2a1da4a61950e9b8789ce9

dashboard_idstringOutput only

UUID identifying the dashboard to which the subscription belongs.

Example: 04aab30f99ea444490c10c85852f216c

subscriberobject

The subscriber that receives the dashboard snapshot. Exactly one of user_subscriber and destination_subscriber must be set.

Show child attributesHide child attributes
user_subscriberobject

The workspace user who receives the subscription.

Show child attributesHide child attributes
user_idint64

The ID of the workspace user who receives the subscription, as returned by the Workspace Users API.

Example: 3294322584244938

destination_subscriberobject

The notification destination that receives the subscription, such as an email list or a Slack or Microsoft Teams channel. Workspace admins configure notification destinations.

Show child attributesHide child attributes
destination_idstring

The UUID of the notification destination that receives the subscription, as returned by the Notification Destinations API.

Example: ce8f875a-11ad-4117-bcc6-c5a542822aee

created_by_user_idint64Output only

UserId of the user who adds subscribers (users or notification destinations) to the dashboard's schedule.

Example: 3294322584244938

etagstring

The etag of the subscription. It must be left empty on create. It can be passed as the etag parameter of the delete method to make sure the subscription has not changed since it was read.

Example: 80611980

create_timestringOutput only

A timestamp indicating when the subscription was created.

update_timestringOutput only

A timestamp indicating when the subscription was last updated.

skip_notifyboolean

Whether the subscription is refresh-only. When true, each scheduled run refreshes the dashboard data for the subscriber without sending a notification. Defaults to false. Refresh-only subscriptions are only allowed on dashboards published without embedded credentials.

Get schedule subscription GA​

GET /api/2.0/lakeview/dashboards/{dashboard_id}/schedules/{schedule_id}/subscriptions/{subscription_id}

Get schedule subscription.

The caller must be a workspace user with one of the following entitlements: Workspace access, Databricks SQL access, or Consumer access.

Account-level users who are not members of the workspace cannot call this endpoint, even if the dashboard has been shared with them.

API scopes: dashboards

Parameters​

dashboard_idstringRequiredpath

UUID identifying the dashboard to which the subscription belongs.

Example: 04aab30f99ea444490c10c85852f216c

schedule_idstringRequiredpath

UUID identifying the schedule to which the subscription belongs.

Example: 01ef0cb45e2a1da4a61950e9b8789ce9

subscription_idstringRequiredpath

UUID identifying the subscription.

Example: 01ee9e6f2a2c1a8d9273d3c3e852fc2b

Response​

Returns the Subscription object.

List schedule subscriptions GA​

GET /api/2.0/lakeview/dashboards/{dashboard_id}/schedules/{schedule_id}/subscriptions

List schedule subscriptions.

The caller must be a workspace user with one of the following entitlements: Workspace access, Databricks SQL access, or Consumer access.

Account-level users who are not members of the workspace cannot call this endpoint, even if the dashboard has been shared with them.

API scopes: dashboards

Parameters​

dashboard_idstringRequiredpath

UUID identifying the dashboard to which the subscriptions belong.

Example: 04aab30f99ea444490c10c85852f216c

schedule_idstringRequiredpath

UUID identifying the schedule to which the subscriptions belong.

Example: 01ef0cb45e2a1da4a61950e9b8789ce9

page_sizeint32[ 1 .. 100 ]query

The number of subscriptions to return per page.

Default: 20

page_tokenstringquery

A page token, received from a previous ListSubscriptions call. Use this to retrieve the subsequent page.

Example: EAI=

Response​

Returns a list of Subscription objects.

Create schedule subscription GA​

POST /api/2.0/lakeview/dashboards/{dashboard_id}/schedules/{schedule_id}/subscriptions

Create schedule subscription. Subscribes a workspace user or a notification destination to the schedule, so that it receives a snapshot of the dashboard each time the schedule runs. Subscribing yourself requires CAN VIEW permission on the dashboard; subscribing another user or a notification destination requires CAN EDIT. On dashboards published without embedded credentials, you can only subscribe yourself. If the subscriber is already subscribed to the schedule, the existing subscription is returned.

The caller must be a workspace user with one of the following entitlements: Workspace access, Databricks SQL access, or Consumer access.

Account-level users who are not members of the workspace cannot call this endpoint, even if the dashboard has been shared with them.

API scopes: dashboards

Parameters​

dashboard_idstringRequiredpath

UUID identifying the dashboard to which the subscription belongs.

Example: 04aab30f99ea444490c10c85852f216c

schedule_idstringRequiredpath

UUID identifying the schedule to which the subscription belongs.

Example: 01ef0cb45e2a1da4a61950e9b8789ce9

Request body​

The subscription to create. A schedule is limited to 100 subscriptions.

subscriberobjectRequired

The subscriber that receives the dashboard snapshot. Exactly one of user_subscriber and destination_subscriber must be set.

Show child attributesHide child attributes
user_subscriberobject

The workspace user who receives the subscription.

Show child attributesHide child attributes
user_idint64Required

The ID of the workspace user who receives the subscription, as returned by the Workspace Users API.

Example: 3294322584244938

destination_subscriberobject

The notification destination that receives the subscription, such as an email list or a Slack or Microsoft Teams channel. Workspace admins configure notification destinations.

Show child attributesHide child attributes
destination_idstringRequired

The UUID of the notification destination that receives the subscription, as returned by the Notification Destinations API.

Example: ce8f875a-11ad-4117-bcc6-c5a542822aee

skip_notifyboolean

Whether the subscription is refresh-only. When true, each scheduled run refreshes the dashboard data for the subscriber without sending a notification. Defaults to false. Refresh-only subscriptions are only allowed on dashboards published without embedded credentials.

Response​

Returns the Subscription object.

Delete schedule subscription GA​

DELETE /api/2.0/lakeview/dashboards/{dashboard_id}/schedules/{schedule_id}/subscriptions/{subscription_id}

Delete schedule subscription. The subscriber receives no further snapshots from the schedule. Deleting your own subscription requires CAN VIEW permission on the dashboard; deleting another user's or a notification destination's subscription requires CAN EDIT.

The caller must be a workspace user with one of the following entitlements: Workspace access, Databricks SQL access, or Consumer access.

Account-level users who are not members of the workspace cannot call this endpoint, even if the dashboard has been shared with them.

API scopes: dashboards

Parameters​

dashboard_idstringRequiredpath

UUID identifying the dashboard to which the subscription belongs.

Example: 04aab30f99ea444490c10c85852f216c

schedule_idstringRequiredpath

UUID identifying the schedule to which the subscription belongs.

Example: 01ef0cb45e2a1da4a61950e9b8789ce9

subscription_idstringRequiredpath

UUID identifying the subscription.

Example: 01ee9e6f2a2c1a8d9273d3c3e852fc2b

etagstringquery

The etag of the subscription, as returned when it was read. If it is provided and no longer matches, the request fails with ABORTED and the subscription is not deleted.

Example: 80611980