---
title: "List automations"
method: GET
path: "/v1/programs/{program_id}/automations"
tags: ["Automations"]
---

# List automations

`GET /v1/programs/{program_id}/automations`

## Request

- Base URL: `https://api.scrip.dev`
- URL: `https://api.scrip.dev/v1/programs/{program_id}/automations`
- Auth: HTTP bearer

List automations for a program.

## Path parameters

- `program_id` string, uuid, required

## Query parameters

- `trigger` 'CRON' | 'ONE_TIME' | 'PARTICIPANT_STATE'
- `scope` 'PROGRAM' | 'PARTICIPANTS'
- `status` 'ACTIVE' | 'PAUSED' | 'COMPLETED' | 'FAILED' | 'ARCHIVED'
- `source` 'API' | 'RULE_ACTION' | 'SYSTEM'
- `search` string
- `limit` integer
- `cursor` string
- `created_after` string, date-time
- `created_before` string, date-time

## Response `200`

Paginated automations

- AutomationListResponse: One page of automations, with the pagination details for the next page.
  - `data` AutomationResponse[]: The automations on this page.
    - `created_at` string, date-time: When this automation was created
    - `description` string: Optional human-readable description of what this automation does
    - `error_message` string: Error message if the one-time automation failed
    - `event_data` object: Event data submitted 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, or JSON-encoded diagnostics for completed runs with CEL eval skips
    - `execution_started_at` string, date-time: When the current fan-out execution started
    - `execution_status` 'IDLE' | 'EXECUTING' | 'COMPLETED' | 'FAILED': Progress of the current run that sends events to participants, separate from `status`. - IDLE: no run is in progress. - EXECUTING: Scrip is sending events to the matching participants. - COMPLETED: the latest run finished; the automation can run again when its trigger is next due. - FAILED: the latest run stopped with an error; the automation can still run again when its trigger is next due.
    - `filter_hints` AutomationFilterHint[]: Checks derived from `participant_filter` that narrow the participants to consider. Scrip still evaluates the full CEL filter for each candidate.
      - `type` 'HAS_TAG' | 'HAS_ATTRIBUTE' | 'HAS_COUNTER', required: Check to apply before evaluating `participant_filter`. - HAS_TAG: value is a participant tag. - HAS_ATTRIBUTE: value is an attribute key. - HAS_COUNTER: value is a counter key.
      - `value` string, required: Non-empty tag value, attribute key, or counter key interpreted according to type.
    - `guard_condition` string: CEL expression evaluated at trigger time; skips the participant if false
    - `id` string, uuid: 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, uuid: Target participant for program-scoped one-time automations
    - `participants_processed` integer: Participants Scrip has sent the event to in the current run so far.
    - `participants_skipped_error` integer: Participants skipped because participant_filter or guard_condition CEL evaluation errored
    - `participants_total` integer: Active participants in the program that the current run checks. When the automation has a `participant_filter` or `guard_condition`, `filter_hints` narrow this count; the filter and guard themselves are not applied, so a finished run can report fewer `participants_processed`.
    - `processed_at` string, date-time: When this one-time automation was processed
    - `program_id` string, uuid: The program this automation belongs to
    - `scope` 'PROGRAM' | 'PARTICIPANTS': Whether the automation sends one event to the program (PROGRAM) or one event to each matching participant (PARTICIPANTS).
    - `source` 'API' | 'RULE_ACTION' | 'SYSTEM': How the automation was created. - API: created through the automations API. - RULE_ACTION: created by a SCHEDULE_EVENT or BROADCAST rule action. - SYSTEM: created by Scrip for scheduled work such as tier expiration.
    - `source_event_id` string, uuid: The event whose processing created this automation. Omitted when no source event is recorded, for example on automations created through the API.
    - `source_rule_id` string, uuid: The rule whose action created this automation. Omitted when no rule action created it, including automations created through the API.
    - `status` 'ACTIVE' | 'PAUSED' | 'COMPLETED' | 'FAILED' | 'ARCHIVED': Whether the automation can fire. - ACTIVE: fires when its trigger is due. - PAUSED: does not fire until you set it back to ACTIVE. - COMPLETED: a one-time automation that has fired; it cannot fire again. - FAILED: stopped after a failure; set it to ACTIVE to try again. - ARCHIVED: removed from use; it never fires again.
    - `trigger` AutomationTrigger: What starts an automation: a cron schedule, a single time, or a participant-state schedule.
      - `cron_expression` string: Cron expression for recurring schedules (cron trigger only)
      - `schedule_config` union: Configuration selected by schedule_type for a PARTICIPANT_STATE trigger. The matching anyOf branch documents its required fields; unrecognized keys are ignored.
        - object: Use when schedule_type is ATTRIBUTE_DATE. Reads a date from each participant's attribute.
          - `attribute_key` string, required: Participant attribute containing the date value.
          - `date_format` 'MM-DD' | 'YYYY-MM-DD', required: Format stored in the participant attribute: MM-DD recurs yearly; YYYY-MM-DD fires for one calendar date.
          - `offset` string: Optional signed duration applied to the attribute date. Accepted units are ns, us or µs, ms, s, m, h, d, and w; units may be combined, while months and years are not accepted.
        - object: Use when schedule_type is INTERVAL. Each participant fires relative to their own subscription time.
          - `interval` string, required: Positive duration between firings. Accepted units are ns, us or µs, ms, s, m, h, d, and w; units may be combined, while months and years are not accepted.
        - object: Use when schedule_type is CRON. All subscribed participants share the same calendar schedule.
          - `expression` string, required: Five-field cron expression or descriptor such as @hourly or @daily; inline timezone directives are not accepted.
        - object: Use when schedule_type is THRESHOLD. Fires after a participant counter satisfies the comparison.
          - `counter_key` string, required: Participant counter to compare.
          - `delay` string, required: Non-negative duration to wait after the comparison matches before firing. Accepted units are ns, us or µs, ms, s, m, h, d, and w; units may be combined, while months and years are not accepted.
          - `operator` '>=' | '>' | '==' | '<=' | '<', required: Comparison applied between the participant counter and threshold.
          - `threshold` number, required: Numeric counter value used by operator for the comparison; explicit 0 is valid.
      - `schedule_type` 'ATTRIBUTE_DATE' | 'INTERVAL' | 'CRON' | 'THRESHOLD': Subscription schedule for a PARTICIPANT_STATE trigger. - ATTRIBUTE_DATE: derive each participant's trigger time from a date-valued attribute. - INTERVAL: fire at a fixed duration relative to each participant's subscription. - CRON: fire all subscribed participants on a shared cron schedule. - THRESHOLD: fire after a participant counter satisfies a comparison.
      - `timezone` string: IANA timezone for schedule evaluation (defaults to UTC)
      - `trigger_at` string, date-time: When to fire (ONE_TIME trigger only, RFC 3339, must be in the future; omit to run now)
      - `type` 'CRON' | 'ONE_TIME' | 'PARTICIPANT_STATE', required: What starts the automation. - CRON: fires repeatedly on `cron_expression` in `timezone`. - ONE_TIME: fires once at `trigger_at`, or as soon as possible when `trigger_at` is omitted. - PARTICIPANT_STATE: keeps a subscription for each matching participant using `schedule_type` and `schedule_config`.
    - `updated_at` string, date-time: When this automation was last updated
    - `warnings` RuleWarning[]: Advisories about `participant_filter` and `guard_condition`, such as a counter, tag or attribute key that no rule in the program writes. They appear on create and update only, and they never block the save.
      - `client_ref` string: The `client_ref` of the rule, when the rule is new.
      - `code` string: What the warning is about. On a rule: `unknown_state_key` (a key no rule writes), `deprecated_alias`, or `possible_unmarked_expression` (a literal that looks like CEL without `${{ }}`). On a simulation: `missing_participant_context`. On a configuration preview, also `stop_after_match_has_no_following_rule`, `unconditional_stop_shadows_following_rules`, or `later_rule_set_retained_empty`.
      - `key` string: The referenced key, as written in the condition.
      - `kind` string: Kind of reference: `counter`, `tag`, `attribute`, or `alias`.
      - `message` string: Human-readable explanation (includes the suggestion when one exists).
      - `rule_id` string: Rule identity is populated for complete-configuration validation. The single-rule authoring surfaces omit these fields.
      - `rule_set_id` string: The id of the rule set that holds the rule.
      - `scope` string: Where the referenced state belongs: `participant`, `program`, or `group`.
      - `suggestion` string: Closest known key, when a near-match exists. Empty otherwise.
  - `pagination` PaginationResponse: Cursor details for a list. `has_more` says whether another page exists, and `next_cursor` is the value to send to get it.
    - `has_more` boolean, required: Whether more results are available beyond this page
    - `next_cursor` string, nullable, required: Cursor to fetch the next page. Null on the last page

## Other responses

- `400`: Invalid parameters (code: validation_error)
- `401`: The API key is missing or not valid. See [Authentication](https://docs.scrip.dev/authentication).
- `404`: Program not found (code: program_not_found)
- `429`: Too many requests. Wait the number of seconds in the `Retry-After` header, then retry. See [Limits and durations](https://docs.scrip.dev/limits#rate-limits).
- `500`: Something failed on Scrip's side. Retry the request, and quote `request_id` if it keeps failing. [Errors](https://docs.scrip.dev/errors) lists every code, and the [API introduction](https://docs.scrip.dev/api-reference/introduction) describes the error format.

---

[API](https://skmtc.dev/scrip/apis/scrip-api.md) · [All operations](https://skmtc.dev/scrip/apis/scrip-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scrip/apis/scrip-api/revisions/c52d35da8d97?raw)