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

# List observed event shapes

> Infer field presence and JSON type distributions from bounded recent external events, compare the immediately preceding window, and surface active-rule reference gaps. Examples are redacted and truncated; findings never block saves or ingestion.

Samples recent events and groups payloads by top-level event type and name. The `inventory` reports field presence, missing and null counts, observed JSON types, and redacted examples. `current_window` and `baseline_window` show drift.

The response also compares observed fields with the fields active rules read (`referenced_never_observed`, `observed_unreferenced`). Use it to check `event.*` names before you write conditions, and to investigate fields that disappeared or changed type. `warnings` never block rule saves or event ingestion.

`window_days`, `sample_limit`, and `as_of` control the sample. Pass `as_of` when you need the same sample again. If payloads were truncated or omitted, `payloads_omitted` and the window byte-limit fields say so.

See [Writing rules: Validate a condition](/guides/writing-rules#validate-a-condition).


## OpenAPI

````yaml GET /v1/programs/{programId}/rules/event-shapes
openapi: 3.0.3
info:
  contact:
    email: support@scrip.dev
    name: Scrip Support
  description: >-
    Scrip is the operating system for rewards programs. Use this REST API to
    define earn and redemption rules, issue and redeem assets, and track every
    movement in a double-entry ledger. Full guides and reference:
    https://docs.scrip.dev


    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
  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}/rules/event-shapes:
    get:
      tags:
        - Rules
      summary: List observed event shapes and rule contract drift
      description: >-
        Infer field presence and JSON type distributions from bounded recent
        external events, compare the immediately preceding window, and surface
        active-rule reference gaps. Examples are redacted and truncated;
        findings never block saves or ingestion.
      operationId: listObservedRuleEventShapes
      parameters:
        - description: Program ID
          in: path
          name: programId
          required: true
          schema:
            format: uuid
            type: string
        - description: Current and baseline window width in days (1-30)
          in: query
          name: window_days
          schema:
            default: 7
            maximum: 30
            minimum: 1
            type: integer
        - description: Maximum events sampled per window (1-100)
          in: query
          name: sample_limit
          schema:
            default: 50
            maximum: 100
            minimum: 1
            type: integer
        - description: >-
            Exclusive end of the current ingestion-time window (RFC3339;
            defaults to request time)
          in: query
          name: as_of
          schema:
            format: date-time
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ObservedEventShapesResponse'
          description: Observed shape inventory and drift warnings
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrBadRequestResponse'
          description: 'Invalid program ID or query parameters (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: '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.ObservedEventShapesResponse:
      properties:
        as_of:
          example: '2026-07-08T00:00:00Z'
          type: string
        baseline_window:
          $ref: '#/components/schemas/handlers.EventShapeWindowResponse'
        current_window:
          $ref: '#/components/schemas/handlers.EventShapeWindowResponse'
        inventory:
          $ref: '#/components/schemas/engine.ObservedEventInventory'
        observed_unreferenced:
          example:
            - event.debug
          items:
            type: string
          type: array
        program_id:
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        referenced_never_observed:
          example:
            - event.ammount
          items:
            type: string
          type: array
        references:
          $ref: '#/components/schemas/handlers.EventReferenceSet'
        warnings:
          items:
            $ref: '#/components/schemas/engine.EventShapeWarning'
          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
    handlers.EventShapeWindowResponse:
      properties:
        from:
          example: '2026-07-01T00:00:00Z'
          type: string
        payload_byte_limit:
          example: 2097152
          type: integer
        payload_bytes_analyzed:
          example: 184320
          type: integer
        payload_per_event_limit:
          example: 262144
          type: integer
        payloads_omitted:
          example: 0
          type: integer
        sample_limit:
          example: 50
          type: integer
        sample_size:
          example: 42
          type: integer
        to:
          example: '2026-07-08T00:00:00Z'
          type: string
      type: object
    engine.ObservedEventInventory:
      properties:
        fields:
          items:
            $ref: '#/components/schemas/engine.ObservedEventField'
          type: array
        payload_bytes_analyzed:
          example: 184320
          type: integer
        payloads_omitted:
          example: 0
          type: integer
        sample_size:
          example: 50
          type: integer
        shapes:
          items:
            $ref: '#/components/schemas/engine.ObservedEventShape'
          type: array
        truncated:
          example: false
          type: boolean
      type: object
    handlers.EventReferenceSet:
      properties:
        dynamic_event_paths:
          description: >-
            Computed/dynamic accesses whose key is only known at evaluation
            time,

            rendered as the known literal prefix plus a "[*]" marker, e.g.
            "event[*]"

            (a computed top-level key) or "event.metadata[*]" (a computed key
            under

            event.metadata). Surfaced, not dropped: a dynamic key still implies
            the

            event must carry whatever it resolves to at runtime.
          example:
            - event.metadata[*]
          items:
            type: string
          type: array
        event_paths:
          description: >-
            Static, fully-literal event field paths, each prefixed with
            "event.",

            e.g. "event.amount" or "event.metadata.category". These are the
            exact

            fields the program's rules read from an event payload.
          example:
            - event.amount
          items:
            type: string
          type: array
      type: object
    engine.EventShapeWarning:
      properties:
        baseline_type:
          example: string
          type: string
        baseline_type_rate:
          example: 1
          type: number
        code:
          example: referenced_event_field_never_observed
          type: string
        current_type:
          example: number
          type: string
        current_type_rate:
          example: 0.8
          type: number
        event_name:
          example: purchase.completed
          type: string
        event_type:
          example: purchase
          type: string
        message:
          type: string
        path:
          example: event.ammount
          type: string
        referenced:
          example: true
          type: boolean
        variant:
          example: dominant
          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
    engine.ObservedEventField:
      properties:
        dominant_type:
          example: number
          type: string
        dominant_type_rate:
          example: 0.7333
          type: number
        missing_count:
          example: 3
          type: integer
        missing_rate:
          example: 0.2
          type: number
        mixed:
          example: false
          type: boolean
        null_count:
          example: 1
          type: integer
        null_rate:
          example: 0.0667
          type: number
        path:
          example: event.amount
          type: string
        presence_rate:
          example: 0.8
          type: number
        present_count:
          example: 12
          type: integer
        types:
          items:
            $ref: '#/components/schemas/engine.ObservedJSONType'
          type: array
      type: object
    engine.ObservedEventShape:
      properties:
        event_name:
          example: purchase.completed
          type: string
        event_type:
          example: purchase
          type: string
        examples:
          items:
            type: object
          type: array
        fields:
          items:
            $ref: '#/components/schemas/engine.ObservedEventField'
          type: array
        first_observed_at:
          example: '2026-07-01T12:00:00Z'
          format: date-time
          type: string
        last_observed_at:
          example: '2026-07-08T12:00:00Z'
          format: date-time
          type: string
        sample_size:
          example: 15
          type: integer
        truncated:
          example: false
          type: boolean
      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
    engine.ObservedJSONType:
      properties:
        count:
          example: 12
          type: integer
        rate:
          example: 0.8
          type: number
        type:
          example: number
          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

````