> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrip.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger an automation

> Manually trigger an automation outside its normal schedule.

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`).

<Warning>
  `participant_state` automations cannot be manually triggered. They fire automatically when participant state matches. To re-evaluate which participants are subscribed, use [refresh subscriptions](/api-reference/automations/refresh-subscriptions) instead.
</Warning>

| 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](/api-reference/automations/refresh-subscriptions) instead |

<Note>
  For usage patterns and examples, see the [Automations guide](/guides/automations).
</Note>


## OpenAPI

````yaml POST /v1/programs/{programId}/automations/{automationId}/trigger
openapi: 3.0.3
info:
  contact:
    email: support@scrip.dev
    name: Scrip Support
    url: https://scrip.dev/support
  description: >-
    Universal Incentive Infrastructure API for managing loyalty programs,
    rewards, and participant balances.


    Scrip provides a complete backend for building incentive and loyalty
    programs. Core concepts:

    - **Programs**: Containers for incentive logic (e.g., "Q1 Sales Bonus",
    "Customer Loyalty")

    - **Assets**: The currency or points being tracked (e.g., "Bonus Points",
    "Cash Rewards")

    - **Participants**: Users who earn and spend assets (identified by
    external_id)

    - **Groups**: Collections of participants for team-based incentives

    - **Rules**: Automated reward logic triggered by events

    - **Events**: Actions that trigger rule evaluation (e.g., "purchase",
    "referral")


    Response formats:

    - **Collection endpoints** return: {"data": [...], "pagination":
    {"has_more": true, "next_cursor": "..."}}

    - **Single-resource endpoints** return the resource directly

    - **Errors** return: {"code": "...", "message": "...", "details": {...}} —
    `details` is an optional object, present on input errors only
  license:
    name: Proprietary
    url: https://scrip.dev/license
  termsOfService: https://scrip.dev/terms
  title: Scrip API
  version: '1.0'
servers:
  - url: https://api.scrip.dev
security: []
tags:
  - description: >-
      Manage incentive programs. Programs are the top-level container for all
      incentive logic.
    name: Programs
  - description: >-
      Manage asset types (currencies, points). Assets define what participants
      can earn and spend.
    name: Assets
  - description: >-
      Manage participants and their balances. Participants are identified by
      external_id from your system.
    name: Participants
  - description: Manage participant groups for team-based incentives.
    name: Groups
  - description: >-
      Manage automated reward rules. Rules define conditions and actions
      triggered by events.
    name: Rules
  - description: Ingest events that trigger rule evaluation and reward distribution.
    name: Events
  - description: Transfer assets between participants.
    name: Transfers
  - description: Access ledger summaries and program activity reports.
    name: Reporting
  - description: >-
      Redeem participant balances for rewards. Supports raw amount redemptions
      and catalog item redemptions.
    name: Redemptions
  - description: >-
      Manage the reward catalog. Create and manage redeemable items with
      inventory tracking.
    name: Rewards
  - description: >-
      Schedule and manage automated event dispatching. Automations generate
      events on cron schedules, at specific times, or by evaluating participant
      state.
    name: Automations
  - description: >-
      Manage tier types and levels within programs. Tiers define status
      hierarchies that participants progress through based on qualification
      rules.
    name: Tiers
  - description: Inspect double-entry ledger records for auditing and reconciliation.
    name: Journal Entries
  - description: >-
      Manage webhook endpoints and delivery logs. Webhooks notify your
      application of real-time events via HTTP POST with HMAC-SHA256 signatures.
    name: Webhooks
paths:
  /v1/programs/{programId}/automations/{automationId}/trigger:
    post:
      tags:
        - Automations
      summary: Trigger an automation
      description: Manually trigger an automation outside its normal schedule.
      operationId: triggerAutomation
      parameters:
        - description: Program ID
          in: path
          name: programId
          required: true
          schema:
            format: uuid
            type: string
        - description: Automation ID
          in: path
          name: automationId
          required: true
          schema:
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.AutomationResponse'
          description: Automation triggered
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrBadRequestResponse'
          description: >-
            Automation cannot be triggered in its current state (code:
            bad_request)
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrUnauthorizedResponse'
          description: 'Missing or invalid credentials (code: unauthorized)'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrNotFoundResponse'
          description: 'Automation or program not found (code: not_found)'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrInternalResponse'
          description: 'Internal server error (code: internal_error)'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  schemas:
    handlers.AutomationResponse:
      properties:
        created_at:
          description: When this automation was created
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        cron_expression:
          description: Cron expression defining the recurring schedule (cron trigger only)
          example: 0 9 * * 1
          type: string
        description:
          description: Optional human-readable description of what this automation does
          example: Sends a weekly reminder event to VIP participants
          type: string
        error_message:
          description: Error message if the one-time automation failed
          example: participant not found
          type: string
        event_name:
          description: The event name generated when this automation fires
          example: weekly_reminder
          type: string
        execution_completed_at:
          description: When the current fan-out execution completed
          example: '2024-01-15T09:00:42Z'
          format: date-time
          type: string
        execution_error:
          description: >-
            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'
          type: string
        execution_started_at:
          description: When the current fan-out execution started
          example: '2024-01-15T09:00:00Z'
          format: date-time
          type: string
        execution_status:
          description: >-
            Current fan-out execution state: idle, pending, executing,
            completed, or failed (participant-scoped only)
          example: completed
          type: string
        filter_hints:
          description: >-
            Optimization hints for the participant filter (e.g., has_tag,
            has_attribute, has_counter)
          items:
            type: object
          type: array
        guard_condition:
          description: >-
            CEL expression evaluated at trigger time; skips the participant if
            false
          example: participant.counters.purchases >= 1
          type: string
        id:
          description: Unique identifier for this automation
          example: 990e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        last_error:
          description: >-
            Error message from the most recent cron execution, if any (cron
            trigger only)
          example: 'failed to enqueue event: queue unavailable'
          type: string
        last_evaluated_at:
          description: >-
            When participant filters were last evaluated (participant_state
            trigger only)
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        last_run_at:
          description: When this automation last fired (cron trigger only)
          example: '2024-01-15T09:00:00Z'
          format: date-time
          type: string
        name:
          description: Human-readable label for this automation
          example: Weekly points reminder
          type: string
        next_run_at:
          description: When this automation will next fire (cron trigger only)
          example: '2024-01-22T09:00:00Z'
          format: date-time
          type: string
        participant_filter:
          description: CEL expression that determines which participants are enrolled
          example: participant.tags.exists(t, t == 'vip')
          type: string
        participant_id:
          description: Target participant for program-scoped one-time automations
          example: 550e8400-e29b-41d4-a716-446655440001
          format: uuid
          type: string
        participants_processed:
          description: Participants processed so far in the current fan-out run
          example: 150
          type: integer
        participants_skipped_error:
          description: >-
            Participants skipped because participant_filter or guard_condition
            CEL evaluation errored
          example: 0
          type: integer
        participants_total:
          description: Total participants to process in the current fan-out run
          example: 150
          type: integer
        payload:
          description: Custom data included in the generated event
          type: object
        processed_at:
          description: When this one-time automation was processed
          example: '2024-02-01T09:00:05Z'
          format: date-time
          type: string
        program_id:
          description: The program this automation belongs to
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        schedule_config:
          description: Configuration for the schedule type (participant_state trigger only)
          type: object
        schedule_type:
          description: >-
            How participant subscriptions are scheduled: ATTRIBUTE_DATE,
            INTERVAL, CRON, or THRESHOLD (participant_state trigger only)
          example: INTERVAL
          type: string
        scope:
          description: >-
            Whether the automation fires once at the program level or fans out
            per participant: program or participants
          example: participants
          type: string
        source:
          description: 'How this automation was created: api or rule_action'
          example: api
          type: string
        status:
          description: 'Current state: active, paused, completed, failed, or archived'
          example: active
          type: string
        timezone:
          description: IANA timezone used for scheduling (e.g., America/New_York)
          example: America/New_York
          type: string
        trigger_at:
          description: >-
            When this automation is scheduled to fire (one_time trigger only,
            RFC 3339)
          example: '2026-02-01T09:00:00Z'
          format: date-time
          type: string
        trigger_type:
          description: >-
            How this automation is triggered: cron, one_time, participant_state,
            or immediate
          example: cron
          type: string
        updated_at:
          description: When this automation was last updated
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        warnings:
          description: >-
            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.
          items:
            $ref: '#/components/schemas/models.RuleWarning'
          type: array
      type: object
    handlers.ErrBadRequestResponse:
      additionalProperties: false
      properties:
        code:
          description: Code is the machine-readable error code
          example: bad_request
          type: string
        details:
          allOf:
            - $ref: '#/components/schemas/handlers.ErrorDetails'
          description: >-
            Details provides optional structured error context (field errors,
            etc.)
        message:
          description: Message is the human-readable error description
          example: Invalid request parameters
          type: string
      type: object
    handlers.ErrUnauthorizedResponse:
      properties:
        code:
          description: Code is the machine-readable error code
          example: unauthorized
          type: string
        details:
          allOf:
            - $ref: '#/components/schemas/handlers.ErrorDetails'
          description: Details provides optional structured error context
        message:
          description: Message is the human-readable error description
          example: Missing or invalid credentials
          type: string
      type: object
    handlers.ErrNotFoundResponse:
      properties:
        code:
          description: Code is the machine-readable error code
          example: not_found
          type: string
        details:
          allOf:
            - $ref: '#/components/schemas/handlers.ErrorDetails'
          description: Details provides optional structured error context
        message:
          description: Message is the human-readable error description
          example: Resource not found
          type: string
      type: object
    handlers.ErrInternalResponse:
      properties:
        code:
          description: Code is the machine-readable error code
          example: internal_error
          type: string
        message:
          description: Message is the human-readable error description
          example: An internal error occurred
          type: string
      type: object
    models.RuleWarning:
      properties:
        code:
          description: >-
            Machine-readable warning category, e.g.
            RuleWarningCodeUnknownStateKey.
          example: unknown_state_key
          type: string
        key:
          description: The referenced key, as written in the condition.
          example: purchaseCnt
          type: string
        kind:
          description: >-
            State kind: StateKindCounter, StateKindTag, StateKindAttribute, or
            StateKindAlias.
          example: counter
          type: string
        message:
          description: >-
            Human-readable explanation (includes the suggestion when one
            exists).
          example: >-
            unknown counter "purchaseCnt" — no rule in this program writes it;
            did you mean "purchase_count"?
          type: string
        scope:
          description: >-
            State scope of the reference: StateScopeParticipant,
            StateScopeProgram, or StateScopeGroup.
          example: participant
          type: string
        suggestion:
          description: Closest known key, when a near-match exists. Empty otherwise.
          example: purchase_count
          type: string
      type: object
    handlers.ErrorDetails:
      description: >-
        Optional structured details about the error. Always a JSON object: a
        `fields` array for validation errors, or flat
        field/reason/expected/received properties for other input errors.
      properties:
        expected:
          description: Expected value or format (non-validation input errors)
          example: uuid
          type: string
        field:
          description: Field name that caused the error (non-validation input errors)
          example: asset_id
          type: string
        fields:
          description: >-
            Fields lists each offending input field on validation_error
            responses.
          items:
            $ref: '#/components/schemas/handlers.ErrorFieldDetail'
          type: array
        reason:
          description: Machine-readable reason code (non-validation input errors)
          example: invalid
          type: string
        received:
          description: Value that was received (non-validation input errors)
          example: not-a-uuid
          type: string
      type: object
    handlers.ErrorFieldDetail:
      description: >-
        A single field-level error: which input field failed, why, and (where
        known) the expected and received values.
      properties:
        expected:
          description: >-
            Expected value or format. Usually a string; for "one of" constraints
            it

            is an array of the allowed values.
        field:
          description: Field name that caused the error
          example: amount
          type: string
        message:
          description: Human-readable explanation (validation errors only)
          example: This field is required
          type: string
        reason:
          description: Machine-readable reason code
          example: required
          type: string
        received:
          description: Value that was received
          example: '-10.00'
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: API key passed in the X-API-Key header.
      in: header
      name: X-API-Key
      type: apiKey
    BearerAuth:
      description: Bearer token passed in the Authorization header (e.g. "Bearer sk_...").
      in: header
      name: Authorization
      type: apiKey

````