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>'
import requests

url = "https://api.scrip.dev/v1/programs/{programId}/automations/{automationId}/trigger"

headers = {"X-API-Key": "<api-key>"}

response = requests.post(url, headers=headers)

print(response.text)
const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.scrip.dev/v1/programs/{programId}/automations/{automationId}/trigger', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.scrip.dev/v1/programs/{programId}/automations/{automationId}/trigger",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"net/http"
"io"
)

func main() {

url := "https://api.scrip.dev/v1/programs/{programId}/automations/{automationId}/trigger"

req, _ := http.NewRequest("POST", url, nil)

req.Header.Add("X-API-Key", "<api-key>")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.scrip.dev/v1/programs/{programId}/automations/{automationId}/trigger")
.header("X-API-Key", "<api-key>")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.scrip.dev/v1/programs/{programId}/automations/{automationId}/trigger")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body
{
  "created_at": "2024-01-15T10:30:00Z",
  "cron_expression": "0 9 * * 1",
  "description": "Sends a weekly reminder event to VIP participants",
  "error_message": "participant not found",
  "event_name": "weekly_reminder",
  "execution_completed_at": "2024-01-15T09:00:42Z",
  "execution_error": "fanout aborted: program is archived",
  "execution_started_at": "2024-01-15T09:00:00Z",
  "execution_status": "completed",
  "filter_hints": [
    {}
  ],
  "guard_condition": "participant.counters.purchases >= 1",
  "id": "990e8400-e29b-41d4-a716-446655440000",
  "last_error": "failed to enqueue event: queue unavailable",
  "last_evaluated_at": "2024-01-15T10:30:00Z",
  "last_run_at": "2024-01-15T09:00:00Z",
  "name": "Weekly points reminder",
  "next_run_at": "2024-01-22T09:00:00Z",
  "participant_filter": "participant.tags.exists(t, t == 'vip')",
  "participant_id": "550e8400-e29b-41d4-a716-446655440001",
  "participants_processed": 150,
  "participants_skipped_error": 0,
  "participants_total": 150,
  "payload": {},
  "processed_at": "2024-02-01T09:00:05Z",
  "program_id": "550e8400-e29b-41d4-a716-446655440000",
  "schedule_config": {},
  "schedule_type": "INTERVAL",
  "scope": "participants",
  "source": "api",
  "status": "active",
  "timezone": "America/New_York",
  "trigger_at": "2026-02-01T09:00:00Z",
  "trigger_type": "cron",
  "updated_at": "2024-01-15T10:30:00Z",
  "warnings": [
    {
      "code": "unknown_state_key",
      "key": "purchaseCnt",
      "kind": "counter",
      "message": "unknown counter \"purchaseCnt\" — no rule in this program writes it; did you mean \"purchase_count\"?",
      "scope": "participant",
      "suggestion": "purchase_count"
    }
  ]
}
{
"code": "bad_request",
"details": {
"expected": "uuid",
"field": "asset_id",
"fields": [
{
"expected": "<unknown>",
"field": "amount",
"message": "This field is required",
"reason": "required",
"received": "-10.00"
}
],
"reason": "invalid",
"received": "not-a-uuid"
},
"message": "Invalid request parameters"
}
{
"code": "unauthorized",
"details": {
"expected": "uuid",
"field": "asset_id",
"fields": [
{
"expected": "<unknown>",
"field": "amount",
"message": "This field is required",
"reason": "required",
"received": "-10.00"
}
],
"reason": "invalid",
"received": "not-a-uuid"
},
"message": "Missing or invalid credentials"
}
{
"code": "not_found",
"details": {
"expected": "uuid",
"field": "asset_id",
"fields": [
{
"expected": "<unknown>",
"field": "amount",
"message": "This field is required",
"reason": "required",
"received": "-10.00"
}
],
"reason": "invalid",
"received": "not-a-uuid"
},
"message": "Resource not found"
}
{
"code": "internal_error",
"message": "An internal error occurred"
}
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

Example:

"2024-01-15T10:30:00Z"

cron_expression
string

Cron expression defining the recurring schedule (cron trigger only)

Example:

"0 9 * * 1"

description
string

Optional human-readable description of what this automation does

Example:

"Sends a weekly reminder event to VIP participants"

error_message
string

Error message if the one-time automation failed

Example:

"participant not found"

event_name
string

The event name generated when this automation fires

Example:

"weekly_reminder"

execution_completed_at
string<date-time>

When the current fan-out execution completed

Example:

"2024-01-15T09:00:42Z"

execution_error
string

Error message if the fan-out execution failed, or JSON-encoded diagnostics for completed runs with CEL eval skips

Example:

"fanout aborted: program is archived"

execution_started_at
string<date-time>

When the current fan-out execution started

Example:

"2024-01-15T09:00:00Z"

execution_status
string

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

Example:

"completed"

filter_hints
object[]

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

guard_condition
string

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

Example:

"participant.counters.purchases >= 1"

id
string<uuid>

Unique identifier for this automation

Example:

"990e8400-e29b-41d4-a716-446655440000"

last_error
string

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

Example:

"failed to enqueue event: queue unavailable"

last_evaluated_at
string<date-time>

When participant filters were last evaluated (participant_state trigger only)

Example:

"2024-01-15T10:30:00Z"

last_run_at
string<date-time>

When this automation last fired (cron trigger only)

Example:

"2024-01-15T09:00:00Z"

name
string

Human-readable label for this automation

Example:

"Weekly points reminder"

next_run_at
string<date-time>

When this automation will next fire (cron trigger only)

Example:

"2024-01-22T09:00:00Z"

participant_filter
string

CEL expression that determines which participants are enrolled

Example:

"participant.tags.exists(t, t == 'vip')"

participant_id
string<uuid>

Target participant for program-scoped one-time automations

Example:

"550e8400-e29b-41d4-a716-446655440001"

participants_processed
integer

Participants processed so far in the current fan-out run

Example:

150

participants_skipped_error
integer

Participants skipped because participant_filter or guard_condition CEL evaluation errored

Example:

0

participants_total
integer

Total participants to process in the current fan-out run

Example:

150

payload
object

Custom data included in the generated event

processed_at
string<date-time>

When this one-time automation was processed

Example:

"2024-02-01T09:00:05Z"

program_id
string<uuid>

The program this automation belongs to

Example:

"550e8400-e29b-41d4-a716-446655440000"

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)

Example:

"INTERVAL"

scope
string

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

Example:

"participants"

source
string

How this automation was created: api or rule_action

Example:

"api"

status
string

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

Example:

"active"

timezone
string

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

Example:

"America/New_York"

trigger_at
string<date-time>

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

Example:

"2026-02-01T09:00:00Z"

trigger_type
string

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

Example:

"cron"

updated_at
string<date-time>

When this automation was last updated

Example:

"2024-01-15T10:30:00Z"

warnings
object[]

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.