Skip to main content
POST
/
v1
/
programs
/
{programId}
/
automations
/
{automationId}
/
trigger
Trigger an automation
curl --request POST \
  --url https://api.scrip.dev/v1/programs/{programId}/automations/{automationId}/trigger \
  --header 'X-API-Key: <api-key>'
{
  "created_at": "2023-11-07T05:31:56Z",
  "cron_expression": "<string>",
  "description": "<string>",
  "error_message": "<string>",
  "event_name": "<string>",
  "execution_completed_at": "2023-11-07T05:31:56Z",
  "execution_error": "<string>",
  "execution_started_at": "2023-11-07T05:31:56Z",
  "execution_status": "<string>",
  "filter_hints": [
    {}
  ],
  "guard_condition": "<string>",
  "id": "<string>",
  "last_error": "<string>",
  "last_evaluated_at": "2023-11-07T05:31:56Z",
  "last_run_at": "2023-11-07T05:31:56Z",
  "name": "<string>",
  "next_run_at": "2023-11-07T05:31:56Z",
  "participant_filter": "<string>",
  "participant_id": "<string>",
  "participants_processed": 123,
  "participants_total": 123,
  "payload": {},
  "processed_at": "2023-11-07T05:31:56Z",
  "program_id": "<string>",
  "schedule_config": {},
  "schedule_type": "<string>",
  "scope": "<string>",
  "source": "<string>",
  "status": "<string>",
  "timezone": "<string>",
  "trigger_at": "2023-11-07T05:31:56Z",
  "trigger_type": "<string>",
  "updated_at": "2023-11-07T05:31:56Z"
}
Manually fires an automation outside its normal schedule. This is useful for testing a new automation before its first scheduled run or for triggering a one-off execution on demand. The automation must be active. For participant-scoped automations, the execution_status must also be idle (no fan-out already running). For program-scoped cron automations, this sets next_run_at to now so the scheduler picks it up immediately. If the automation doesn’t meet these requirements, the API returns 400 with message “Automation cannot be triggered (must be active and idle or cron+program)”. This includes automations that have been canceled (which are archived and no longer active).
participant_state automations cannot be manually triggered. They fire automatically when participant state matches. To re-evaluate which participants are subscribed, use refresh subscriptions instead.
Trigger TypeScopeSupported?
cronprogramYes
cronparticipantsYes (must be idle)
one_timeparticipantsYes (must be idle)
immediateparticipantsYes (must be idle)
one_timeprogramNo — fires at trigger_at only
participant_stateparticipantsNo — use refresh subscriptions instead
For usage patterns and examples, see the Automations guide.

Authorizations

​
X-API-Key
string
header
required

API key passed in the X-API-Key header.

Path Parameters

​
programId
string<uuid>
required

Program ID

​
automationId
string<uuid>
required

Automation ID

Response

Automation triggered

​
created_at
string<date-time>

When this automation was created

​
cron_expression
string

Cron expression defining the recurring schedule (cron trigger only)

​
description
string

Optional human-readable description of what this automation does

​
error_message
string

Error message if the one-time automation failed

​
event_name
string

The event name generated when this automation fires

​
execution_completed_at
string<date-time>

When the current fan-out execution completed

​
execution_error
string

Error message if the fan-out execution failed

​
execution_started_at
string<date-time>

When the current fan-out execution started

​
execution_status
string

Current fan-out execution state: idle, pending, executing, completed, or failed (participant-scoped only)

​
filter_hints
object[]

Optimization hints for the participant filter (e.g., has_tag, has_attribute)

​
guard_condition
string

CEL expression evaluated at trigger time; skips the participant if false

​
id
string

Unique identifier for this automation

​
last_error
string

Error message from the most recent cron execution, if any (cron trigger only)

​
last_evaluated_at
string<date-time>

When participant filters were last evaluated (participant_state trigger only)

​
last_run_at
string<date-time>

When this automation last fired (cron trigger only)

​
name
string

Human-readable label for this automation

​
next_run_at
string<date-time>

When this automation will next fire (cron trigger only)

​
participant_filter
string

CEL expression that determines which participants are enrolled

​
participant_id
string

Target participant for program-scoped one-time automations

​
participants_processed
integer

Participants processed so far in the current fan-out run

​
participants_total
integer

Total participants to process in the current fan-out run

​
payload
object

Custom data included in the generated event

​
processed_at
string<date-time>

When this one-time automation was processed

​
program_id
string

The program this automation belongs to

​
schedule_config
object

Configuration for the schedule type (participant_state trigger only)

​
schedule_type
string

How participant subscriptions are scheduled: ATTRIBUTE_DATE, INTERVAL, CRON, or THRESHOLD (participant_state trigger only)

​
scope
string

Whether the automation fires once at the program level or fans out per participant: program or participants

​
source
string

How this automation was created: api or rule_action

​
status
string

Current state: active, paused, completed, failed, or archived

​
timezone
string

IANA timezone used for scheduling (e.g., America/New_York)

​
trigger_at
string<date-time>

When this automation is scheduled to fire (one_time trigger only, RFC 3339)

​
trigger_type
string

How this automation is triggered: cron, one_time, participant_state, or immediate

​
updated_at
string<date-time>

When this automation was last updated