--- title: "List trigger subscriptions on a connection" method: GET path: "/api/v1/connections/{connection_id}/trigger-subscriptions" tags: ["Triggers"] --- # List trigger subscriptions on a connection `GET /api/v1/connections/{connection_id}/trigger-subscriptions` ## Request - Base URL: `https://$SCALEKIT_ENVIRONMENT_URL` - URL: `https://$SCALEKIT_ENVIRONMENT_URL/api/v1/connections/{connection_id}/trigger-subscriptions` - Auth: OAuth 2 - Client credentials - Token URL: `https://$SCALEKIT_ENVIRONMENT_URL/oauth/token` - TypeScript: (a function with typed inputs; its response is checked against the schema) Lists the trigger subscriptions on a connection, newest first. Use this endpoint to show which accounts are subscribed to which triggers, and to check whether each subscription is delivering. Pass the connection ID in the path. Filter by trigger_name and statuses, and page with page_size and page_token. For a polled trigger, each subscription returns both the interval you requested and the interval it actually runs at, which can be slower when the environment's polling budget is shared across many subscriptions. A polled subscription also returns its poll state: when it last ran, why the last run failed, and whether polling is backed off. Returns one page of subscriptions, the next and previous page tokens, total_size, and status_counts, which counts subscriptions per status across every page. ## Path parameters - `connection_id` string, required ## Query parameters - `trigger_name` string - `statuses` string[] - `page_size` integer - `page_token` string ## Response `200` One page of the connection's trigger subscriptions, plus page tokens, the total match count and per-status counts - TriggersListTriggerSubscriptionsResponse - `next_page_token` string: Pass as page_token to read the next page. Empty when there is no next page. - `prev_page_token` string: Pass as page_token to read the previous page. Empty when there is no previous page. - `status_counts` object: 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 a customer switches between status filters. - `subscriptions` TriggersTriggerSubscription[]: One page of the connection's trigger subscriptions that match the filters, newest first. - `account_health` 'READY' | 'AWAITING_CONFIRMATION' | 'WRONG_APP' | 'DISCONNECTED' | 'NEEDS_REAUTHENTICATION': A connected account's own state, evaluated for what the trigger in question routes by: a webhook trigger needs the provider workspace captured, and an account-scoped webhook trigger the provider user too. - READY: The account can receive triggers. - AWAITING_CONFIRMATION: Connected and working, but Scalekit has not confirmed which provider workspace or user it belongs to, so inbound events cannot be routed to it. - WRONG_APP: Authorized under a different OAuth app than the connection now uses. - DISCONNECTED: The account was disconnected. - NEEDS_REAUTHENTICATION: The credential itself is unusable: it has expired, or the account has not finished connecting. - `config` object: 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_id` string: ID of the subscribed connected account. Empty for a connection-scoped subscription. - `connected_account_identifier` string: The identifier the connected account was created with, such as your app's user ID or the user's email address, so a client can label the subscription without fetching every account separately. 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_id` string: ID of the connection the subscription belongs to. - `created_at` string, date-time: When the subscription was created. Returned so a list can be ordered or explained by age without a second lookup. - `delivery_scope` 'ACCOUNT' | 'CONNECTION': Whether a trigger delivers once per connected account or once for the whole connection. Set by the trigger, not chosen by the subscriber. A polled trigger polls with one connected account's credential, so a polled trigger that is connection-scoped is reported as unavailable. - ACCOUNT: One event per subscribed connected account. For a webhook trigger, an event is delivered for an account only when the event's provider workspace and user match the account's; a polled trigger polls each account with that account's own credential. Subscribed on a specific connected account. - CONNECTION: One event for the whole connection, whatever accounts exist on it. Subscribed on the connection itself, naming no account. - `effective_interval_seconds` integer: 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. - `id` string: Unique identifier of the trigger subscription. - `poll_state` TriggersTriggerPollState: The state of a poll subscription's feed, as of its most recent run. Read from the feed's own stored state on every request rather than derived, so a feed that is failing, rate limited, or held off is visible without looking at logs. A subscription whose status is ACTIVE can still be failing every run; this is where that shows. - `backoff_until` string, date-time: 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_failures` integer: How many runs in a row have failed. Zero after any successful run. - `last_error` string: 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_code` 'RATE_LIMITED' | 'CREDENTIAL_REVOKED' | 'INVALID_CONFIGURATION' | 'PROVIDER_ERROR' | 'DELIVERY_FAILED' | 'TIMED_OUT' | 'POLL_FAILED': Why a poll subscription's most recent run failed. - RATE_LIMITED: The provider asked Scalekit to slow down. Polling resumes after backoff_until. - CREDENTIAL_REVOKED: The connected account's authorization was revoked or has expired. Reconnect the account. - INVALID_CONFIGURATION: The subscription's configuration does not produce a valid request for this trigger. Update the subscription's configuration. - PROVIDER_ERROR: The provider returned an error. Retried on the next run. - DELIVERY_FAILED: Events could not be handed to the delivery service. Retried on the next run. - TIMED_OUT: The run timed out before it finished. Retried on the next run. - POLL_FAILED: The run failed for a reason none of the other codes describes. Retried on the next run. - `last_run_at` string, date-time: 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_at` string, date-time: 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. - `provider` string: The provider the trigger belongs to. - `requested_interval_seconds` integer: 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. - `status` 'ACTIVE' | 'THROTTLED' | 'PAUSED' | 'PAUSED_CREDENTIAL': Why a subscription is or is not currently delivering. - ACTIVE: Delivering. For a polled trigger, at the requested interval. - THROTTLED: Running slower than requested, not stopped. Still delivering. - PAUSED: Stopped by the customer. - PAUSED_CREDENTIAL: Stopped because the account's credential no longer works. Distinct from PAUSED so the two have distinguishable explanations for missing events. - `trigger_name` string: Name of the subscribed trigger, as returned by ListAvailableTriggers. - `total_size` integer: How many subscriptions match the filters in total, across every page. ## Other responses - `400`: Invalid 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 - `404`: Not found - the connection does not exist in this environment, or Triggers is not enabled for the environment - `500`: Internal error - the subscriptions could not be read; retry the request ## Changes - **2026-10-30** `f47f1022d844`: 1 info - endpoint added [Operation history](https://skmtc.dev/scalekit/apis/scalekit-api-reference/changes/api/v1/connections/:connection_id/trigger-subscriptions/get.md) --- [API](https://skmtc.dev/scalekit/apis/scalekit-api-reference.md) - [All operations](https://skmtc.dev/scalekit/apis/scalekit-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/scalekit/apis/scalekit-api-reference/revisions/f47f1022d844?raw)