Trigger an automation
Manually trigger an automation outside its normal schedule.
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).
| Trigger Type | Scope | Supported? |
|---|---|---|
cron | program | Yes |
cron | participants | Yes (must be idle) |
one_time | participants | Yes (must be idle) |
immediate | participants | Yes (must be idle) |
one_time | program | No; fires at trigger_at only |
participant_state | participants | No; use refresh subscriptions instead |
Authorizations
API key passed in the X-API-Key header.
Path Parameters
Program ID
Automation ID
Response
Automation triggered
When this automation was created
"2024-01-15T10:30:00Z"
Cron expression defining the recurring schedule (cron trigger only)
"0 9 * * 1"
Optional human-readable description of what this automation does
"Sends a weekly reminder event to VIP participants"
Error message if the one-time automation failed
"participant not found"
The event name generated when this automation fires
"weekly_reminder"
When the current fan-out execution completed
"2024-01-15T09:00:42Z"
Error message if the fan-out execution failed, or JSON-encoded diagnostics for completed runs with CEL eval skips
"fanout aborted: program is archived"
When the current fan-out execution started
"2024-01-15T09:00:00Z"
Current fan-out execution state: idle, pending, executing, completed, or failed (participant-scoped only)
"completed"
Optimization hints for the participant filter (e.g., has_tag, has_attribute, has_counter)
CEL expression evaluated at trigger time; skips the participant if false
"participant.counters.purchases >= 1"
Unique identifier for this automation
"990e8400-e29b-41d4-a716-446655440000"
Error message from the most recent cron execution, if any (cron trigger only)
"failed to enqueue event: queue unavailable"
When participant filters were last evaluated (participant_state trigger only)
"2024-01-15T10:30:00Z"
When this automation last fired (cron trigger only)
"2024-01-15T09:00:00Z"
Human-readable label for this automation
"Weekly points reminder"
When this automation will next fire (cron trigger only)
"2024-01-22T09:00:00Z"
CEL expression that determines which participants are enrolled
"participant.tags.exists(t, t == 'vip')"
Target participant for program-scoped one-time automations
"550e8400-e29b-41d4-a716-446655440001"
Participants processed so far in the current fan-out run
150
Participants skipped because participant_filter or guard_condition CEL evaluation errored
0
Total participants to process in the current fan-out run
150
Custom data included in the generated event
When this one-time automation was processed
"2024-02-01T09:00:05Z"
The program this automation belongs to
"550e8400-e29b-41d4-a716-446655440000"
Configuration for the schedule type (participant_state trigger only)
How participant subscriptions are scheduled: ATTRIBUTE_DATE, INTERVAL, CRON, or THRESHOLD (participant_state trigger only)
"INTERVAL"
Whether the automation fires once at the program level or fans out per participant: program or participants
"participants"
How this automation was created: api or rule_action
"api"
Current state: active, paused, completed, failed, or archived
"active"
IANA timezone used for scheduling (e.g., America/New_York)
"America/New_York"
When this automation is scheduled to fire (one_time trigger only, RFC 3339)
"2026-02-01T09:00:00Z"
How this automation is triggered: cron, one_time, participant_state, or immediate
"cron"
When this automation was last updated
"2024-01-15T10:30:00Z"
Non-blocking advisories about participant_filter/guard_condition — e.g. a counter/tag/attribute key no rule in the program writes. Present on create/update only; never blocks the save.