List trigger subscriptions Beta

GET/api/v1/connections/{connection_id}/trigger-subscriptions

This endpoint is in beta. Its request and response may change.

Lists the trigger subscriptions on a connection, newest first. Filter by trigger_name and statuses. A polling subscription also returns when it last ran and why its last run failed. status_counts counts the subscriptions in each status across every page.

This page as markdown Triggers overview

REST
Python

Authorization

Authorization: Bearer $TOKEN, an access token from the client credentials grant. See Authentication.

Path parameters

connection_idstringrequired

ID of the connection, in this environment. Up to 64 characters.

Query parameters

page_sizeinteger

How many subscriptions to return. Defaults to 10; a larger value than 100 is capped at 100 rather than refused.

page_tokenstring

The next_page_token or prev_page_token from a previous response. Omit it to read the first page. A value that is not a token from a previous response is refused with 400.

statusesarray of string (enum)

Narrows the list to subscriptions in these statuses, at most 4. Omit it for every status; TRIGGER_SUBSCRIPTION_STATUS_UNSPECIFIED is refused. Does not affect status_counts, so a client filtering to one status still sees the totals for all of them. - ACTIVE: Delivering. For a polled trigger, at the requested interval. - THROTTLED: Running slower than requested, not stopped. Still delivering. - PAUSED: Stopped by you. - PAUSED_CREDENTIAL: Stopped because the account's credential no longer works. Distinct from PAUSED so the two have distinguishable explanations for missing events.

trigger_namestring

Narrows the list to one trigger's subscriptions. Omit it to list every subscription on the connection.

scalekit_client.actions.triggers.list_subscriptions

List a connection's trigger subscriptions, one page at a time.

scalekit_client.actions.triggers.list_subscriptions(
    connection_id: str,
    trigger_name: str | None = None,
    statuses: Sequence[TriggerSubscriptionStatus | str | int] | None = None,
    page_size: int | None = None,
    page_token: str | None = None,
) -> ListTriggerSubscriptionsResponse

Parameters

connection_idstrrequired

The connection (conn_...).

trigger_namestr | None

Only subscriptions to this trigger.

statusesSequence[TriggerSubscriptionStatus | str | int] | None

Only subscriptions in these states: TriggerSubscriptionStatus members, their names, or raw numbers.

page_sizeint | None

Subscriptions per page; the server caps it at 100.

page_tokenstr | None

next_page_token or prev_page_token of a previous page.

Returns ListTriggerSubscriptionsResponse: One page of subscriptions, total_size and status_counts.

From scalekit-sdk-python 2.23.0.

Response 200

next_page_tokenstring

Pass as page_token to read the next page. Empty when there is no next page.

prev_page_tokenstring

Pass as page_token to read the previous page. Empty when there is no previous page.

status_countsobject

How many subscriptions sit in each status, keyed by the status name. Counted over the whole matching set rather than the current page, so a client can show per-status totals without fetching every page. Honours trigger_name but ignores statuses, so the totals stay still while you switch between status filters.

subscriptionsarray of object

One page of the connection's trigger subscriptions that match the filters, newest first.

Show 14 child attributes

account_healthstring (enum)

How the subscribed account stands for this trigger. AWAITING_CONFIRMATION means Scalekit cannot route this trigger's events to the account yet, so the subscription will not fire until the account's user reconnects it. Absent for connection-scoped subscriptions.

READYAWAITING_CONFIRMATIONWRONG_APPDISCONNECTEDNEEDS_REAUTHENTICATION

configobject

The subscription's filter values, keyed by the trigger's config_fields keys. Keys are returned exactly as stored; send them back without changing their case.

connected_account_idstring

ID of the subscribed connected account. Empty for a connection-scoped subscription.

connected_account_identifierstring

The identifier the connected account was created with, your app's ID for the user, such as user_123, so you can label the subscription without fetching each account. Empty for a connection-scoped subscription, and empty when the account has no identifier recorded — fall back to connected_account_id rather than showing a blank.

connection_idstring

ID of the connection the subscription belongs to.

created_atstring

When the subscription was created. Returned so a list can be ordered or explained by age without a second lookup.

delivery_scopestring (enum)

Whether this subscription receives one event per connected account or one event for the whole connection. A connection-scoped subscription carries no connected_account_id — the connection is the only recipient.

ACCOUNTCONNECTION

effective_interval_secondsinteger

The polling interval, in seconds, the subscription actually runs at. Larger than requested_interval_seconds when the environment's polling budget is shared across many polled subscriptions; the subscription's status is then THROTTLED. Zero for a webhook trigger.

idstring

Unique identifier of the trigger subscription.

poll_stateobject

How a POLL subscription's feed is doing: when it last ran, why the last run failed, and whether polling is held off. Absent for a WEBHOOK subscription, which is never polled.

Show 6 child attributes

backoff_untilstring

Polling is held off until this time, because the provider asked Scalekit to slow down or a run failed in a way retrying cannot fix. Absent when no hold-off has been recorded. A time in the past means the hold-off has ended and the next scheduled run polls again.

consecutive_failuresinteger

How many runs in a row have failed. Zero after any successful run.

last_errorstring

A short, human-readable explanation of why the most recent run failed and what happens next. Empty when the most recent run succeeded or no run has happened yet. Chosen from a fixed set of messages by last_error_code and never contains the provider's response. The wording can change: match on last_error_code, not on this text.

last_error_codestring (enum)

Why the most recent run failed, as a stable code to branch on. TRIGGER_POLL_ERROR_CODE_UNSPECIFIED when the most recent run succeeded or no run has happened yet. CREDENTIAL_REVOKED and INVALID_CONFIGURATION need a change from you before polling can succeed; every other code is retried automatically.

RATE_LIMITEDCREDENTIAL_REVOKEDINVALID_CONFIGURATIONPROVIDER_ERRORDELIVERY_FAILEDTIMED_OUTPOLL_FAILED

last_run_atstring

When Scalekit last polled the provider for this subscription, whether or not the run succeeded. Absent until the first run. A value far older than the effective interval means the feed has stopped running.

watermark_updated_atstring

When the feed's position last moved forward — the last time a run found and delivered newer events. A run that finds nothing new leaves it unchanged.

providerstring

The provider the trigger belongs to.

requested_interval_secondsinteger

The polling interval, in seconds, the subscription asked for, or the trigger's default when it did not set one. Returned next to effective_interval_seconds so a subscription running slower than requested is visible. Zero for a webhook trigger.

statusstring (enum)

Whether the subscription is delivering. ACTIVE — delivering. THROTTLED — delivering, but polling slower than requested; compare requested_interval_seconds with effective_interval_seconds. PAUSED — stopped by you. PAUSED_CREDENTIAL — stopped because the account's credential no longer works.

ACTIVETHROTTLEDPAUSEDPAUSED_CREDENTIAL

trigger_namestring

Name of the subscribed trigger, as returned by List available triggers.

total_sizeinteger

How many subscriptions match the filters in total, across every page.

Errors

Every error has the same body: code, message and details. See Errors and rate limits.

400Invalid request - connection_id is not a valid connection ID, page_token is not a token from a previous response, or statuses holds TRIGGER_SUBSCRIPTION_STATUS_UNSPECIFIED or an unknown status

404Not found - the connection does not exist in this environment, or Triggers isn't turned on for your environment

500Internal error - the subscriptions could not be read; retry the request

Request

REST
Python

curl -sS -G -X GET \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/connections/conn_133400101014995480/trigger-subscriptions" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "trigger_name=salesforce_lead_created"

result = scalekit_client.actions.triggers.list_subscriptions(
    connection_id="conn_133400101014995480",
    trigger_name="salesforce_lead_created",
)

Response 200

1
{
2
  "subscriptions": [
3
    {
4
      "id": "trgs_141020933185734981",
5
      "connected_account_id": "ca_133400349586228019",
6
      "connected_account_identifier": "user_123",
7
      "connection_id": "conn_133400101014995480",
8
      "provider": "salesforce",
9
      "trigger_name": "salesforce_lead_created",
10
      "status": "ACTIVE",
11
      "delivery_scope": "ACCOUNT",
12
      "requested_interval_seconds": 300,
13
      "effective_interval_seconds": 300,
14
      "config": {
15
        "lead_source": "Web"
16
      },
17
      "created_at": "2026-10-28T09:12:44.120Z",
18
      "poll_state": {
19
        "last_run_at": "2026-10-28T09:17:44.310Z",
20
        "last_error": "",
21
        "last_error_code": "TRIGGER_POLL_ERROR_CODE_UNSPECIFIED",
22
        "consecutive_failures": 0,
23
        "watermark_updated_at": "2026-10-28T09:17:44.310Z"
24
      },
25
      "account_health": "READY"
26
    }
27
  ],
28
  "next_page_token": "",
29
  "prev_page_token": "",
30
  "total_size": 1,
31
  "status_counts": {
32
    "ACTIVE": 1
33
  }
34
}