Subscribe several accounts to a trigger Beta

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

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

Subscribes up to 100 connected accounts to one trigger with the same filters, and returns a result for each account. An account that can't subscribe doesn't stop the others: its result is REFUSED, NOT_FOUND or FAILED, with a reason. Retrying the request is safe; an account subscribed earlier comes back as ALREADY_SUBSCRIBED. For a per-connection trigger, send an empty connected_account_ids.

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 applied to every account in the batch, keyed by the trigger's config_fields keys. Each account gets its own subscription with these values, so subscribing the same accounts again with different values adds subscriptions rather than replacing these. Invalid values refuse the whole request.

connected_account_idsarray of string

Connected accounts to subscribe, at most 100 — one page of the account picker — with no repeats. Which to send depends on the trigger's delivery_scope, from List available triggers. For an ACCOUNT-scoped trigger, list at least one account; an empty list refuses the whole request with a 400. For a CONNECTION-scoped trigger, send an empty list: the trigger is subscribed once, on the connection itself, and results holds exactly one result, with an empty connected_account_id. Naming accounts for a connection-scoped trigger refuses each of them (REFUSED), since that trigger is not subscribed per account.

interval_secondsinteger

Polling interval in seconds, for a polled trigger only, applied to every account in the batch. Omit it to use the trigger's default_interval_seconds. A value below the trigger's min_interval_seconds, or any value for a webhook trigger, refuses the whole request. A large batch of polled subscriptions shares the environment's polling budget, so the subscriptions can run slower than requested; effective_interval_seconds on each subscription shows the interval it runs at.

scalekit_client.actions.triggers.batch_create_subscriptions

Subscribe up to 100 connected accounts to a trigger in one call. Not atomic: each account gets its own outcome in results (CREATED, ALREADY_SUBSCRIBED, REFUSED, NOT_FOUND, FAILED), and those never raise. Safe to call again for the FAILED ones. For a connection-scoped trigger, leave connected_account_ids out.

scalekit_client.actions.triggers.batch_create_subscriptions(
    connection_id: str,
    trigger_name: str,
    connected_account_ids: Sequence[str] | None = None,
    interval: timedelta | None = None,
    config: Mapping[str, str] | None = None,
) -> BatchCreateTriggerSubscriptionsResponse

Parameters

connection_idstrrequired

The connection (conn_...).

trigger_namestrrequired

AvailableTrigger.name.

connected_account_idsSequence[str] | None

The accounts (ca_...), unique.

intervaltimedelta | None

Poll interval, in whole seconds (see create_subscription).

configMapping[str, str] | None

Values for the trigger's config_fields.

Returns BatchCreateTriggerSubscriptionsResponse: Per-account results and created_count.

From scalekit-sdk-python 2.23.0.

Response 200

created_countinteger

How many subscriptions this call created. Excludes accounts that were already subscribed.

resultsarray of object

One result per requested account, in the order the accounts were sent, so a client can pair them up positionally without matching on id. For a connection-scoped trigger subscribed with an empty connected_account_ids, exactly one result, with an empty connected_account_id.

Show 4 child attributes

connected_account_idstring

The connected account ID this result is for, as sent in the request.

outcomestring (enum)

What happened to this account. CREATED — a subscription was created. ALREADY_SUBSCRIBED — the account already had a subscription to this trigger with these exact config values; nothing new was created, and list subscriptions to read the existing one. REFUSED — the account cannot receive this trigger; reason says why and what to do. NOT_FOUND — no such account on this connection in this environment. FAILED — the attempt failed for a reason unrelated to the account; nothing was created, and retrying may succeed.

CREATEDALREADY_SUBSCRIBEDREFUSEDNOT_FOUNDFAILED

reasonstring

Why the account was not subscribed, and for a refusal what to do about it, in one sentence — the same text Subscribe to a trigger returns for the same account. Empty for CREATED.

subscriptionobject

The created subscription, for CREATED. Absent for every other outcome, including ALREADY_SUBSCRIBED.

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.

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, nothing created - connection_id or an entry of connected_account_ids is malformed; config is invalid for this trigger; interval_seconds is below the trigger's minimum, or is set for a webhook trigger; the trigger polls and is connection-scoped, which is not supported; or connected_account_ids is empty for a trigger that is subscribed per connected account. A well-formed ID naming an account that does not exist is not this case: it comes back as a per-account NOT_FOUND result with a 200, so one bad ID in a batch of a hundred does not discard the ninety-nine that would have succeeded

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

500Internal error - the connection or the trigger's definition could not be read, so no account was processed; retry the request

Request

REST
Python

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

from datetime import timedelta

result = scalekit_client.actions.triggers.batch_create_subscriptions(
    connection_id="conn_133400101014995480",
    trigger_name="salesforce_lead_created",
    connected_account_ids=["ca_133400349586228019", "ca_133400349586231107"],
    interval=timedelta(minutes=5),
    config={"lead_source": "Web"},
)

Response 200

1
{
2
  "results": [
3
    {
4
      "connected_account_id": "ca_133400349586228019",
5
      "outcome": "ALREADY_SUBSCRIBED",
6
      "reason": "this principal already has a subscription to this trigger with these exact settings"
7
    },
8
    {
9
      "connected_account_id": "ca_133400349586231107",
10
      "outcome": "CREATED",
11
      "reason": "",
12
      "subscription": {
13
        "id": "trgs_141020933185736602",
14
        "connected_account_id": "ca_133400349586231107",
15
        "connected_account_identifier": "user_456",
16
        "connection_id": "conn_133400101014995480",
17
        "provider": "salesforce",
18
        "trigger_name": "salesforce_lead_created",
19
        "status": "ACTIVE",
20
        "delivery_scope": "ACCOUNT",
21
        "requested_interval_seconds": 300,
22
        "effective_interval_seconds": 300,
23
        "config": {
24
          "lead_source": "Web"
25
        },
26
        "created_at": "2026-10-28T09:20:02.480Z",
27
        "poll_state": {
28
          "last_error": "",
29
          "last_error_code": "TRIGGER_POLL_ERROR_CODE_UNSPECIFIED",
30
          "consecutive_failures": 0,
31
          "watermark_updated_at": "2026-10-28T09:20:02.480Z"
32
        },
33
        "account_health": "READY"
34
      }
35
    }
36
  ],
37
  "created_count": 1
38
}