Subscribe to a trigger Beta

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

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

Subscribes one connected account, or the whole connection, to a trigger. Pass connected_account_id for a per-account trigger, and leave it out for a per-connection trigger. Set the trigger's filters in config, using the keys from the trigger's config_fields. For a polling trigger, interval_seconds sets how often Scalekit checks the app; it defaults to the trigger's default interval, and a value below its minimum is refused.

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.

Body

trigger_namestringrequired

Name of the trigger to subscribe to, as returned in the name field of List available triggers. Up to 128 characters.

configobject

Filter values for the subscription, keyed by the trigger's config_fields keys, spelled exactly as returned. Every required field must be set. An unknown key, or a value longer than 512 characters, is refused. Subscribing again with different values creates another subscription; subscribing again with identical values returns 409.

connected_account_idstring

Connected account to subscribe on, for an account-scoped trigger. Omit it for a connection-scoped trigger — the trigger is then subscribed on the connection itself and no account is named. Whether omitting it is valid depends on the trigger's own delivery_scope.

interval_secondsinteger

Polling interval in seconds, for a polled trigger only. Omit it to use the trigger's default_interval_seconds. A value below the trigger's min_interval_seconds is refused, naming the minimum, rather than rounded up. Setting it for a webhook trigger is refused. The subscription can run slower than requested when the environment's polling budget is shared across many polled subscriptions; effective_interval_seconds on the response shows the interval it runs at.

scalekit_client.actions.triggers.create_subscription

Subscribe a connected account, or the whole connection, to a trigger. Not retried on UNAVAILABLE: a retry could create the subscription twice. Creating the same subscription again raises ScalekitConflictException.

scalekit_client.actions.triggers.create_subscription(
    connection_id: str,
    trigger_name: str,
    connected_account_id: str | None = None,
    interval: timedelta | None = None,
    config: Mapping[str, str] | None = None,
) -> TriggerSubscription

Parameters

connection_idstrrequired

The connection (conn_...).

trigger_namestrrequired

AvailableTrigger.name.

connected_account_idstr | None

The account (ca_...). Leave out only for a connection-scoped trigger.

intervaltimedelta | None

Poll interval for a poll trigger, in whole seconds; at least the trigger's min_interval. Leave out for the default and for webhook triggers.

configMapping[str, str] | None

Values for the trigger's config_fields.

Returns TriggerSubscription: The new subscription.

From scalekit-sdk-python 2.23.0.

Response 200

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.

Errors

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

400Invalid request - the message names what to change. Returned when an ID is malformed; config holds an unknown key, misses a required key, or holds a value longer than 512 characters; interval_seconds is below the trigger's minimum, or is set for a webhook trigger; connected_account_id is missing for an account-scoped trigger, or present for a connection-scoped one; the trigger polls and is connection-scoped, which is not supported; or the account cannot receive the trigger because its grant lacks a required scope or the bot install the trigger needs, it was authorized under a different app, the trigger needs your own provider app, its provider workspace or user is not yet confirmed, or it holds no usable credential

404Not found - the connection or connected account does not exist in this environment, the connected account belongs to a different connection, the connection's provider publishes no trigger with this name, or Triggers isn't turned on for your environment

409Conflict - this account, or this connection for a connection-scoped trigger, already has a subscription to this trigger with exactly these config values

500Internal error - the subscription could not be created; nothing was created

503Service unavailable - polling for the new subscription could not be scheduled, so the subscription was not created; retry the same request

Request

REST
Python

curl -sS -X POST \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/connections/conn_133400101014995480/trigger-subscriptions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_name": "salesforce_lead_created",
    "connected_account_id": "ca_133400349586228019",
    "config": {
      "lead_source": "Web"
    },
    "interval_seconds": 300
  }'

from datetime import timedelta

result = scalekit_client.actions.triggers.create_subscription(
    connection_id="conn_133400101014995480",
    trigger_name="salesforce_lead_created",
    connected_account_id="ca_133400349586228019",
    interval=timedelta(minutes=5),
    config={"lead_source": "Web"},
)

Response 200

1
{
2
  "id": "trgs_141020933185734981",
3
  "connected_account_id": "ca_133400349586228019",
4
  "connected_account_identifier": "user_123",
5
  "connection_id": "conn_133400101014995480",
6
  "provider": "salesforce",
7
  "trigger_name": "salesforce_lead_created",
8
  "status": "ACTIVE",
9
  "delivery_scope": "ACCOUNT",
10
  "requested_interval_seconds": 300,
11
  "effective_interval_seconds": 300,
12
  "config": {
13
    "lead_source": "Web"
14
  },
15
  "created_at": "2026-10-28T09:12:44.120Z",
16
  "poll_state": {
17
    "last_error": "",
18
    "last_error_code": "TRIGGER_POLL_ERROR_CODE_UNSPECIFIED",
19
    "consecutive_failures": 0,
20
    "watermark_updated_at": "2026-10-28T09:12:44.120Z"
21
  },
22
  "account_health": "READY"
23
}