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

# List scenarios

> Returns a paginated list of scenarios in the workspace.

By default, returns all scenarios in the workspace (admin view).
Use filters to narrow down results by owner, visibility, or access.




## OpenAPI

````yaml /api-reference/openapi.yaml get /scenarios
openapi: 3.0.3
info:
  title: Exec API
  version: '1.0'
  description: >
    REST API for programmatic access to your Exec workspace.


    Use the Exec API to read workspace data, list members, retrieve group
    information,

    and create interactive scenario creation sessions.


    ## Authentication

    All requests require a valid API key passed in the Authorization header:

    ```

    Authorization: Bearer exec_live_...

    ```


    Create API keys in your workspace settings under **Settings > API**.
servers:
  - url: https://api.exec.com/rest/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Knowledge Hub - Folders
    x-group: Knowledge Hub
  - name: Knowledge Hub - Pages
    x-group: Knowledge Hub
  - name: Knowledge Hub - Sources
    x-group: Knowledge Hub
paths:
  /scenarios:
    get:
      tags:
        - Scenarios
      summary: List scenarios
      description: |
        Returns a paginated list of scenarios in the workspace.

        By default, returns all scenarios in the workspace (admin view).
        Use filters to narrow down results by owner, visibility, or access.
      operationId: listScenarios
      parameters:
        - name: page
          in: query
          description: Page number (1-indexed)
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: page_size
          in: query
          description: Number of results per page (max 100)
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
        - name: owner_email
          in: query
          description: Filter by scenario owner's email address
          schema:
            type: string
            format: email
        - name: visible_to_email
          in: query
          description: >-
            Filter by who can access the scenario (checks owner, user shares,
            group shares, workspace shares)
          schema:
            type: string
            format: email
        - name: visibility
          in: query
          description: Filter by visibility scope
          schema:
            type: string
            enum:
              - private
              - workspace
        - name: include_archived
          in: query
          description: Include archived scenarios in results
          schema:
            type: boolean
            default: false
        - name: skill_ids
          in: query
          description: Comma-separated skill IDs to filter by
          schema:
            type: string
        - name: collection_ids
          in: query
          description: Comma-separated collection IDs to filter by
          schema:
            type: string
        - name: include
          in: query
          description: >
            Comma-separated list of optional data to include.

            Available values: `skills` (list of skills evaluated by each
            scenario).
          schema:
            type: string
            example: skills
      responses:
        '200':
          description: List of scenarios
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Scenario'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                data:
                  - id: s1c2e3n4a5r6
                    name: Discovery Call with IT Director
                    description: Practice handling objections from skeptical IT buyers
                    slug: discovery-call-it-director
                    url: >-
                      https://acme-corp.app.exec.com/scenarios/discovery-call-it-director
                    difficulty: medium
                    context: >-
                      The buyer is the VP of Engineering at a Series B fintech.
                      They have an active RFP out for an observability tool and
                      your competitor presented yesterday.
                    objective: >-
                      Qualify the opportunity and book a follow-up meeting with
                      the economic buyer.

                      ##### Outcomes to Avoid:

                      - Discounting before discovery

                      - Skipping the budget conversation

                      - Committing to a custom integration without scoping
                    language: English
                    visibility: workspace
                    owner:
                      id: u7v8w9x0y1z2
                      email: jane@acme.com
                      first_name: Jane
                      last_name: Smith
                    created_at: '2024-01-15T10:30:00Z'
                    updated_at: '2024-02-01T14:20:00Z'
                pagination:
                  page: 1
                  page_size: 50
                  total_count: 125
                  total_pages: 3
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Scenario:
      type: object
      properties:
        id:
          type: string
          description: Unique scenario identifier
        name:
          type: string
          description: Scenario name
        description:
          type: string
          nullable: true
          description: Short description of the scenario
        slug:
          type: string
          description: URL-friendly scenario identifier
        url:
          type: string
          format: uri
          description: Direct link to the scenario
        difficulty:
          type: string
          description: Scenario difficulty level
          enum:
            - easy
            - medium
            - hard
            - very_hard
            - custom
        context:
          type: string
          nullable: true
          description: >
            The scenario's context - background and setup information that
            frames

            the roleplay (e.g., the buyer's company, current situation, recent

            events). Plain text, may contain newlines. May be null for scenarios

            that haven't filled in this section.
          example: >-
            The buyer is the VP of Engineering at a Series B fintech. They have
            an active RFP out for an observability tool and your competitor
            presented yesterday.
        objective:
          type: string
          nullable: true
          description: |
            The learner's objective for the scenario. The value is markdown and
            includes an embedded "Outcomes to Avoid" subsection separated by the
            delimiter `##### Outcomes to Avoid:`, followed by a bulleted list.
            Consumers who want the two pieces separately can split on that
            delimiter.
          example: >
            Qualify the opportunity and book a follow-up meeting with the
            economic buyer.

            ##### Outcomes to Avoid:

            - Discounting before discovery

            - Skipping the budget conversation

            - Committing to a custom integration without scoping
        language:
          type: string
          description: Scenario language
        visibility:
          type: string
          description: Sharing scope of the scenario
          enum:
            - private
            - workspace
        owner:
          $ref: '#/components/schemas/User'
          nullable: true
          description: User who owns the scenario
        created_at:
          type: string
          format: date-time
          description: When the scenario was created
        updated_at:
          type: string
          format: date-time
          description: When the scenario was last updated
        skills:
          type: array
          nullable: true
          description: >-
            Skills evaluated by this scenario (only included when requested via
            `?include=skills`)
          items:
            $ref: '#/components/schemas/SkillRef'
    Pagination:
      type: object
      properties:
        page:
          type: integer
          description: Current page number
        page_size:
          type: integer
          description: Number of items per page
        total_count:
          type: integer
          description: Total number of items
        total_pages:
          type: integer
          description: Total number of pages
    User:
      type: object
      properties:
        id:
          type: string
          description: Unique user identifier
        email:
          type: string
          format: email
          description: User's email address
        first_name:
          type: string
          description: User's first name
        last_name:
          type: string
          description: User's last name
    SkillRef:
      type: object
      description: A compact skill reference for embedding in other responses.
      properties:
        id:
          type: string
          description: Unique skill identifier
        name:
          type: string
          description: Skill name
        slug:
          type: string
          description: URL-friendly skill identifier
    ValidationErrorDetail:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: Error category (e.g., "invalid_request")
            code:
              type: string
              description: Specific error code (e.g., "user_not_found")
            message:
              type: string
              description: Human-readable error message
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorDetail'
          example:
            error:
              type: invalid_request
              code: invalid_pagination
              message: Invalid pagination parameters
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorDetail'
          example:
            error:
              type: authentication_error
              code: invalid_api_key
              message: Invalid or inactive API key
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        API key created in Settings > API.

        Format: `exec_live_` followed by 40 alphanumeric characters.

````