> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# 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.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_id` | string | Yes | ID of the connection, in this environment. Up to 64 characters. |

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page_size` | integer | No | How many subscriptions to return. Defaults to 10; a larger value than 100 is capped at 100 rather than refused. |
| `page_token` | string | No | 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. |
| `statuses` | array of string (enum) | No | 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_name` | string | No | Narrows the list to one trigger's subscriptions. Omit it to list every subscription on the connection. |

**Response (200)**

| Name | Type | Description |
| --- | --- | --- |
| `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 you switch between status filters. |
| `subscriptions` | array of object | One page of the connection's trigger subscriptions that match the filters, newest first. |
| `subscriptions.account_health` | string (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. One of: `READY`, `AWAITING_CONFIRMATION`, `WRONG_APP`, `DISCONNECTED`, `NEEDS_REAUTHENTICATION`. |
| `subscriptions.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. |
| `subscriptions.connected_account_id` | string | ID of the subscribed connected account. Empty for a connection-scoped subscription. |
| `subscriptions.connected_account_identifier` | string | 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. |
| `subscriptions.connection_id` | string | ID of the connection the subscription belongs to. |
| `subscriptions.created_at` | string | When the subscription was created. Returned so a list can be ordered or explained by age without a second lookup. |
| `subscriptions.delivery_scope` | string (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. One of: `ACCOUNT`, `CONNECTION`. |
| `subscriptions.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. |
| `subscriptions.id` | string | Unique identifier of the trigger subscription. |
| `subscriptions.poll_state` | object | 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. |
| `subscriptions.poll_state.backoff_until` | string | 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. |
| `subscriptions.poll_state.consecutive_failures` | integer | How many runs in a row have failed. Zero after any successful run. |
| `subscriptions.poll_state.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. |
| `subscriptions.poll_state.last_error_code` | string (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. One of: `RATE_LIMITED`, `CREDENTIAL_REVOKED`, `INVALID_CONFIGURATION`, `PROVIDER_ERROR`, `DELIVERY_FAILED`, `TIMED_OUT`, `POLL_FAILED`. |
| `subscriptions.poll_state.last_run_at` | string | 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. |
| `subscriptions.poll_state.watermark_updated_at` | string | 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. |
| `subscriptions.provider` | string | The provider the trigger belongs to. |
| `subscriptions.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. |
| `subscriptions.status` | string (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. One of: `ACTIVE`, `THROTTLED`, `PAUSED`, `PAUSED_CREDENTIAL`. |
| `subscriptions.trigger_name` | string | Name of the subscribed trigger, as returned by [List available triggers](https://docs.scalekit.com/agentkit/reference/triggers/list-available-triggers/). |
| `total_size` | integer | How many subscriptions match the filters in total, across every page. |

**Errors**

- `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 isn't turned on for your environment
- `500`: Internal error - the subscriptions could not be read; retry the request

**Request**

```bash
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"
```

**Response**

```json
{
  "subscriptions": [
    {
      "id": "trgs_141020933185734981",
      "connected_account_id": "ca_133400349586228019",
      "connected_account_identifier": "user_123",
      "connection_id": "conn_133400101014995480",
      "provider": "salesforce",
      "trigger_name": "salesforce_lead_created",
      "status": "ACTIVE",
      "delivery_scope": "ACCOUNT",
      "requested_interval_seconds": 300,
      "effective_interval_seconds": 300,
      "config": {
        "lead_source": "Web"
      },
      "created_at": "2026-10-28T09:12:44.120Z",
      "poll_state": {
        "last_run_at": "2026-10-28T09:17:44.310Z",
        "last_error": "",
        "last_error_code": "TRIGGER_POLL_ERROR_CODE_UNSPECIFIED",
        "consecutive_failures": 0,
        "watermark_updated_at": "2026-10-28T09:17:44.310Z"
      },
      "account_health": "READY"
    }
  ],
  "next_page_token": "",
  "prev_page_token": "",
  "total_size": 1,
  "status_counts": {
    "ACTIVE": 1
  }
}
```

**Python SDK:** `scalekit_client.actions.triggers.list_subscriptions`

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

```python
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
```

Example:

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

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_id` | `str` | Yes | The connection (`conn_...`). |
| `trigger_name` | `str \| None` | No | Only subscriptions to this trigger. |
| `statuses` | `Sequence[TriggerSubscriptionStatus \| str \| int] \| None` | No | Only subscriptions in these states: `TriggerSubscriptionStatus` members, their names, or raw numbers. |
| `page_size` | `int \| None` | No | Subscriptions per page; the server caps it at 100. |
| `page_token` | `str \| None` | No | `next_page_token` or `prev_page_token` of a previous page. |

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


Part of [Triggers](https://docs.scalekit.com/agentkit/reference/triggers/) in the [AgentKit API reference](https://docs.scalekit.com/agentkit/reference/). Authentication: https://docs.scalekit.com/agentkit/reference/authentication.md. Errors and rate limits: https://docs.scalekit.com/agentkit/reference/errors.md. Pagination: https://docs.scalekit.com/agentkit/reference/pagination.md


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |