> ## 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.

# Get event by idempotency key

> Look up an event by its idempotency key and program ID.

Looks up an event by its `idempotency_key` and `program_id`. Both are required as query parameters because idempotency keys are scoped per program.

This is the preferred lookup method when you have the key you used at ingestion time but not the event ID. It reads the same store and returns the same event object as the [get-by-ID endpoint](/api-reference/events/get-an-event), including processing status and rule evaluation results. It is subject to the same brief post-accept visibility window: a freshly accepted event may `404` here until the async consumer materializes it. Poll until it resolves. An event that was rejected during async processing resolves as status `FAILED` with an `error_code`, not as a `404`.

Pass `include_skipped=true` to include rule evaluations with `SKIPPED_ERROR` or `SKIPPED_TIMEOUT` status.

<Note>
  For usage patterns and examples, see the [Event Processing guide](/guides/event-processing).
</Note>


## OpenAPI

````yaml GET /v1/events/by-key
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/events/by-key:
    get:
      tags:
        - Events
      summary: Get event by idempotency key
      description: Look up an event by its idempotency key and program ID.
      operationId: getEventByKey
      parameters:
        - description: Program ID
          in: query
          name: program_id
          required: true
          schema:
            format: uuid
            type: string
        - description: Idempotency key
          in: query
          name: idempotency_key
          required: true
          schema:
            type: string
        - description: Include skipped rule evaluations (SKIPPED_ERROR, SKIPPED_TIMEOUT)
          in: query
          name: include_skipped
          schema:
            default: false
            type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.EventDetailResponse'
          description: Event details with rule executions
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrBadRequestResponse'
          description: 'Invalid query parameters (code: bad_request)'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrUnauthorizedResponse'
          description: 'Missing or invalid credentials (code: unauthorized)'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrForbiddenResponse'
          description: 'Insufficient permissions (code: forbidden)'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrNotFoundResponse'
          description: 'Resource 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.EventDetailResponse:
      properties:
        created_at:
          description: When this event was created
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        error_code:
          description: >-
            Machine-readable failure code for a terminal FAILED event, when one
            is available

            (e.g. program_not_found, participant_suspended,
            participant_inactive). NULL when

            the event did not fail or the failure carried no stable code.
          example: program_not_found
          type: string
        error_message:
          description: Error details if the event failed during processing
          example: rule condition evaluation failed
          type: string
        event_data:
          description: Original event data payload
          type: object
        event_timestamp:
          description: When the event occurred (from the ingestion request)
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        event_type:
          description: 'Event type: EXTERNAL (API-ingested) or SYSTEM (internally generated)'
          example: EXTERNAL
          type: string
        external_id:
          description: >-
            Your system's identifier for the participant (the value provided at
            ingestion)
          example: user_abc123
          type: string
        id:
          description: Unique identifier for this event
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        idempotency_key:
          description: Client-provided unique key for deduplication
          example: order-12345-completed
          type: string
        participant_id:
          description: >-
            Participant UUID, resolved from external_id if one was provided at
            ingestion
          example: 550e8400-e29b-41d4-a716-446655440002
          format: uuid
          type: string
        processed_at:
          description: >-
            When the event finished processing (null while pending or
            processing)
          example: '2024-01-15T10:30:02Z'
          format: date-time
          type: string
        program_id:
          description: Program this event belongs to
          example: 550e8400-e29b-41d4-a716-446655440001
          format: uuid
          type: string
        received_at:
          description: When Scrip received the event
          example: '2024-01-15T10:30:01Z'
          format: date-time
          type: string
        recipient_id:
          description: Reward recipient UUID, if different from the triggering participant
          example: 550e8400-e29b-41d4-a716-446655440003
          format: uuid
          type: string
        rule_evaluations:
          description: >-
            RuleEvaluations lists all rules that were evaluated for this event
            and their outcomes
          items:
            $ref: '#/components/schemas/handlers.RuleEvaluationResponse'
          type: array
        status:
          description: >-
            Processing status: RECEIVED, PENDING, PROCESSING, COMPLETED, or
            FAILED
          example: COMPLETED
          type: string
        updated_at:
          description: When this event was last updated
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
      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.ErrForbiddenResponse:
      properties:
        code:
          description: Code is the machine-readable error code
          example: forbidden
          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: Insufficient permissions for this action
          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
    handlers.RuleEvaluationResponse:
      properties:
        created_at:
          description: When the evaluation occurred
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        error_message:
          description: Error details if the rule failed during execution
          example: condition evaluation failed
          type: string
        id:
          description: Unique identifier for this evaluation record
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        reason:
          description: Why the rule was skipped (only present for SKIPPED status)
          example: OUTSIDE_TIME_WINDOW
          type: string
        rule_history_id:
          description: >-
            Snapshot of the rule version that was active when this evaluation
            occurred
          example: 550e8400-e29b-41d4-a716-446655440003
          format: uuid
          type: string
        rule_id:
          description: Rule that was evaluated
          example: 550e8400-e29b-41d4-a716-446655440001
          format: uuid
          type: string
        rule_name:
          description: Display name of the rule
          example: Welcome Bonus
          type: string
        status:
          description: 'Evaluation result: SUCCESS, FAILED, or SKIPPED'
          example: SUCCESS
          type: string
        stopped_by_rule_id:
          description: The rule whose stop_after_match caused this rule to be skipped
          example: 550e8400-e29b-41d4-a716-446655440002
          format: uuid
          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

````