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

# List Scenario Runs

> Retrieve execution records of your scenarios - useful for **debugging webhook subscriptions**: see whether the event fired, whether the conditions matched (`conditionsResult`), whether the webhook request succeeded (`success`), and per-step timings and errors.

**Required token scopes:** `View scenarios runs`


## OpenAPI

````yaml he/api-reference/openapi.json GET /scenarios/runs
openapi: 3.1.0
info:
  title: Texter API V2
  version: 2.0.0
  description: >-
    The **Texter API** lets your developers control the Texter platform
    programmatically:


    - Manage and send your WhatsApp template messages

    - Retrieve chats by ID or by various filters

    - Assign and resolve conversations

    - Send session messages into active chats

    - Manage labels

    - Monitor and resolve channel health issues

    - Subscribe to real-time webhook events

    - Manage quick replies (coming soon)


    For any questions please contact [Texter
    Support](https://wa.me/972586640430).
  contact:
    name: Texter Support
    url: https://wa.me/972586640430
servers:
  - url: https://{projectID}.texterchat.com/server/api/v2
    description: Your Texter environment. Replace projectID with your project subdomain
    variables:
      projectID:
        default: demo
        description: >-
          Your unique project subdomain. If your environment URL is
          https://demo.texterchat.com, your projectID is "demo"
security:
  - bearerAuth: []
tags:
  - name: Manage Templates
    description: >-
      Create, localize, submit, update, delete and send WhatsApp template
      messages, and retrieve approved templates for your connected WhatsApp
      accounts.


      **Suggested token for this group** - create one API token with the scopes:
      *Send template messages*, *View template messages*, *Manage WhatsApp
      templates*, *Manage all chats*, *List all chats* (the last two also cover
      the Templates Subscriptions group). Each endpoint below also lists the
      exact scopes it needs.
  - name: Templates Subscriptions
    description: >-
      Manage recipient subscriptions for WhatsApp template messages -
      unsubscribe or resubscribe recipients, and list unsubscribed users across
      all channels or for a specific account.


      **Suggested token for this group** - scopes: *Manage all chats*, *List all
      chats*. Each endpoint below also lists the exact scopes it needs.
  - name: Messages
    description: >-
      Retrieve message history from a chat, or send new session messages - text,
      media, buttons, lists, contact cards and locations - within the active
      WhatsApp 24-hour session window.


      **Suggested token for this group** - scopes: *Send session message*, *View
      all chats*. Each endpoint below also lists the exact scopes it needs.
  - name: Chats
    description: >-
      Fetch chat details, search conversations, update chat properties, assign
      or resolve chats, and manage their CRM metadata.


      **Suggested token for this group** - scopes: *Manage all chats*, *List all
      chats*, *Send session message*. Each endpoint below also lists the exact
      scopes it needs.
  - name: Labels
    description: >-
      Create and edit labels, assign or remove them from chats, retrieve label
      data, or delete labels from your inbox.


      **Suggested token for this group** - scopes: *Manage labels*, *Manage all
      chats* (needed for managing labels on chats). Each endpoint below also
      lists the exact scopes it needs.
  - name: Channels
    description: >-
      Monitor and maintain the health of connected messaging channels - retrieve
      active channel health problems, filter them by severity or account, and
      mark issues as resolved.


      **Suggested token for this group** - scopes: *Manage channels*. Each
      endpoint below also lists the exact scopes it needs.
  - name: Quick Replies
    description: >-
      Manage quick replies - prepared messages agents can send into matching
      chats with one click. Quick replies marked with `aiQuickReply` client
      metadata appear as **AI suggestions** in the Texter inbox (see Create
      Quick Reply for the full flow).


      **Suggested token for this group** - scopes: *View quick replies*, *Manage
      quick replies*. Each endpoint below also lists the exact scopes it needs.
  - name: Files
    description: >-
      Generate public access links to media files stored in Texter.


      **Suggested token for this group** - scopes: *View all files*, *View all
      chats* (both required). Each endpoint below also lists the exact scopes it
      needs.
  - name: Subscribe to Events
    description: >-
      Register webhooks for events occurring in your Texter environment. Under
      the hood this uses **Scenarios** - a workflow automation feature within
      Texter. To make integration easy, pre-defined templates are provided:
      import a scenario JSON, plug in your webhook URL and user UID, and the
      subscription is active.


      See the **Webhook Events** pages for the payload your URL receives for
      each event.


      **Suggested token for this group** - scopes: *View scenarios*, *Create
      scenarios*, *Delete scenarios*, *Activate/inactivate scenarios*, *Manage
      scenarios on behalf of user*. Each endpoint below also lists the exact
      scopes it needs.


      If the provided templates don't satisfy your needs, contact [Texter
      Support](https://wa.me/972586640430) and we'll gladly help modify any
      triggers, conditions or actions for your webhook.
  - name: Scenarios (Advanced)
    description: >-
      Full programmatic control over scenarios for advanced automations: create
      scenarios from scratch, copy them, edit drafts, publish revisions, inspect
      execution runs, and discover the available building blocks (events,
      conditions, loaders, actions). For plain webhook subscriptions, the
      **Subscribe to Events** group with its ready-made templates is the simpler
      path.


      **Suggested token for this group** - scopes: *View scenarios*, *Create
      scenarios*, *Edit scenarios*, *Delete scenarios*, *Activate/inactivate
      scenarios*, *Manage scenarios on behalf of user*, *View scenarios runs*.
      Each endpoint below also lists the exact scopes it needs.
paths:
  /scenarios/runs:
    get:
      tags:
        - Scenarios (Advanced)
      summary: List Scenario Runs
      description: >-
        Retrieve execution records of your scenarios - useful for **debugging
        webhook subscriptions**: see whether the event fired, whether the
        conditions matched (`conditionsResult`), whether the webhook request
        succeeded (`success`), and per-step timings and errors.


        **Required token scopes:** `View scenarios runs`
      operationId: list-scenario-runs
      parameters:
        - name: scenarioId
          in: query
          schema:
            type: string
          description: Filter runs of a specific scenario (subscription)
        - name: version
          in: query
          schema:
            type: string
            pattern: ^[0-9]+$
          description: Filter by revision version (1-100000)
        - name: success
          in: query
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          description: Filter by run success
        - name: conditionsResult
          in: query
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          description: Filter by overall conditions result
        - name: sortStarted
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
          description: Sort by start time
        - name: sortExecutionTime
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
          description: Sort by execution time
        - name: limit
          in: query
          schema:
            type: string
            pattern: ^[0-9]+$
          description: Maximum results to return (1-10000)
        - name: skip
          in: query
          schema:
            type: string
            pattern: ^[0-9]+$
          description: Results to skip (0-1000000)
      responses:
        '200':
          description: >-
            The matching runs and total count. Field-by-field reference: [The
            Scenario Run object](/he/api-reference/objects/scenario-run)
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: number
                  runs:
                    type: array
                    items:
                      $ref: '#/components/schemas/ScenarioRun'
        '400':
          description: Invalid query values
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid token, or missing required scope
      x-codeSamples:
        - lang: bash
          label: Latest runs of one subscription
          source: >-
            curl -g
            "https://YOUR_PROJECT.texterchat.com/server/api/v2/scenarios/runs?scenarioId=6970b3c1d2e3f40123456789&sortStarted=desc&limit=20"
            \
              -H "Authorization: Bearer YOUR_API_TOKEN"
        - lang: bash
          label: Only failed runs
          source: >-
            curl -g
            "https://YOUR_PROJECT.texterchat.com/server/api/v2/scenarios/runs?scenarioId=6970b3c1d2e3f40123456789&success=false"
            \
              -H "Authorization: Bearer YOUR_API_TOKEN"
        - lang: bash
          label: Fired but conditions didn't match
          source: >-
            curl -g
            "https://YOUR_PROJECT.texterchat.com/server/api/v2/scenarios/runs?scenarioId=6970b3c1d2e3f40123456789&conditionsResult=false"
            \
              -H "Authorization: Bearer YOUR_API_TOKEN"
components:
  schemas:
    ScenarioRun:
      type: object
      description: A single execution record of a scenario (event subscription)
      properties:
        _id:
          type: string
          description: ID of the run result document
        scenarioId:
          type: string
          description: ID of the scenario
        version:
          type: number
          description: Version of the scenario revision that ran
        success:
          type: boolean
          description: Whether the run completed successfully
        started:
          type: number
          description: Timestamp the run started (epoch ms)
        executionTime:
          type: number
          description: Total execution time in milliseconds
        conditionsResult:
          type: boolean
          description: >-
            Overall result of the conditions, when applicable - `false` means
            the run stopped before actions
        steps:
          type: array
          description: >-
            Per-step results. Each step has `type` (`event` | `loader` |
            `condition` | `action` | `loop`), `name`, `executionTime` and
            optional `error`. Loaders add `position`/`index`/computed params;
            conditions add `result`/`groupIndex`/`index`; actions add
            `output`/`index`; loops add `iterations[]` (sub-run results with
            their own steps)
          items:
            type: object
            additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
      required:
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API token generated in Texter: gear icon → Developers → API Tokens. When
        creating a token, assign it the scopes required by the endpoints you
        plan to call - each endpoint lists its required scopes.

````