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

# List evaluator scenarios

> Returns a paginated list of evaluator scenarios in your organization, optionally filtered by test agent or tags.



## OpenAPI

````yaml /openapi/source/external/inference/inference-ai-tests.json get /ai/tests/test_framework/v1/scenarios
openapi: 3.1.0
info:
  version: 2.0.0
  title: Telnyx API
  x-latency-category: responsive
  x-endpoint-cost: light
  description: SIP trunking, SMS, MMS, Call Control and Telephony Data Services.
  contact:
    email: support@telnyx.com
servers:
  - url: https://api.telnyx.com/v2
    description: Version 2.0.0 of the Telnyx API
security:
  - bearerAuth: []
tags:
  - name: AI Tests
    description: >-
      Test agents, evaluator scenarios, metrics, and run results for the AI test
      framework.
paths:
  /ai/tests/test_framework/v1/scenarios:
    get:
      tags:
        - AI Tests
      summary: List evaluator scenarios
      description: >-
        Returns a paginated list of evaluator scenarios in your organization,
        optionally filtered by test agent or tags.
      operationId: list_evaluator_scenarios
      parameters:
        - name: page
          in: query
          required: false
          description: Page number (1-based).
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: page_size
          in: query
          required: false
          description: Number of results per page.
          schema:
            type: integer
            minimum: 1
            maximum: 250
            default: 25
        - name: agent_id
          in: query
          required: false
          description: Filter scenarios belonging to the specified test agent.
          schema:
            type: integer
        - name: assistant_id
          in: query
          required: false
          description: Filter scenarios belonging to the specified Telnyx assistant.
          schema:
            type: string
        - name: tags
          in: query
          required: false
          description: Filter scenarios by a comma-separated list of tags.
          schema:
            type: string
      responses:
        '200':
          description: Paginated list of evaluator scenarios.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluatorScenarioListResponse'
              example:
                count: 1
                next: null
                previous: null
                results:
                  - id: 9512
                    name: Refund escalation flow
                    personality: 4643
                    personality_name: Interruptive (High)
                    phone_number: '+13125550188'
                    expected_outcome_prompt: >-
                      The assistant explains the refund policy and offers
                      escalation.
                    instructions: >-
                      Call the support line and demand a refund for a damaged
                      product.
                    scenario_language: en
                    scenario_type: workflow
                    tags:
                      - support
                      - regression
                    agent: 1259
                    inbound_phone_number: null
                    inbound_phone_number_data: null
                    metrics:
                      - 266881
                      - 266882
                    metric_names:
                      - Greeting quality
                      - Escalation quality
                    first_message: Hi, I want a refund.
                    tool_ids: []
                    test_profile: null
                    test_profile_data: null
                    dynamic_variable_values: null
                    created_at: '2026-10-13T18:04:05.123456Z'
                    updated_at: '2026-10-13T18:04:05.123456Z'
                    last_updated_by: 1
                    folder_path: null
        '400':
          description: Bad Request. The AI Tests service rejected the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiTestsErrorResponse'
              example:
                errors:
                  - code: '10015'
                    title: Bad Request
                    detail: The AI Tests service rejected the request.
        '401':
          description: Unauthorized. Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiTestsErrorResponse'
              example:
                errors:
                  - code: '10003'
                    title: Unauthorized
                    detail: The API key is missing or invalid.
        '404':
          description: >-
            Not Found. The requested resource does not exist or is not enabled
            for your account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiTestsErrorResponse'
              example:
                errors:
                  - code: '10005'
                    title: Not Found
                    detail: The requested resource or URL could not be found.
        '422':
          description: Unprocessable Entity. A validation error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiTestsErrorResponse'
              example:
                errors:
                  - code: '10018'
                    title: Unprocessable Entity
                    detail: Validation failed for the request payload.
        '429':
          description: Too Many Requests. The AI Tests service rate-limited the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiTestsErrorResponse'
              example:
                errors:
                  - code: '10029'
                    title: Too Many Requests
                    detail: Too many requests; retry later.
        '503':
          description: Service Unavailable. The AI Tests service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiTestsErrorResponse'
              example:
                errors:
                  - code: '10063'
                    title: Service Unavailable
                    detail: The test framework service is temporarily unavailable.
components:
  schemas:
    EvaluatorScenarioListResponse:
      type: object
      properties:
        count:
          type: integer
        next:
          type:
            - string
            - 'null'
          format: uri
        previous:
          type:
            - string
            - 'null'
          format: uri
        results:
          type: array
          items:
            $ref: '#/components/schemas/EvaluatorScenario'
      required:
        - count
        - next
        - previous
        - results
      example:
        count: 1
        next: null
        previous: null
        results:
          - id: 9512
            name: Refund escalation flow
            personality: 4643
            personality_name: Interruptive (High)
            phone_number: '+13125550188'
            expected_outcome_prompt: The assistant explains the refund policy and offers escalation.
            instructions: Call the support line and demand a refund for a damaged product.
            scenario_language: en
            scenario_type: workflow
            tags:
              - support
              - regression
            agent: 1259
            inbound_phone_number: null
            inbound_phone_number_data: null
            metrics:
              - 266881
              - 266882
            metric_names:
              - Greeting quality
              - Escalation quality
            first_message: Hi, I want a refund.
            tool_ids: []
            test_profile: null
            test_profile_data: null
            dynamic_variable_values: null
            created_at: '2026-10-13T18:04:05.123456Z'
            updated_at: '2026-10-13T18:04:05.123456Z'
            last_updated_by: 1
            folder_path: null
    AiTestsErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                description: Telnyx error code.
              title:
                type: string
              detail:
                type: string
              source:
                type: object
                properties:
                  pointer:
                    type: string
            required:
              - code
              - title
      required:
        - errors
    EvaluatorScenario:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        personality:
          type:
            - integer
            - 'null'
          description: ID of the test personality the caller simulates.
        personality_name:
          type: string
        phone_number:
          type: string
          description: Outbound phone number used to place the simulated call.
        expected_outcome_prompt:
          type: string
          description: >-
            What a successful conversation looks like; scored by the
            expected-outcome metric.
        instructions:
          type: string
          description: What the simulated caller should do during the conversation.
        scenario_language:
          type:
            - string
            - 'null'
        scenario_type:
          type: string
          description: 'Type of scenario: workflow, red_teaming_voice, or red_teaming_text.'
        tags:
          type: array
          items:
            type: string
        agent:
          type:
            - integer
            - 'null'
          description: ID of the test agent the scenario runs against.
        inbound_phone_number:
          type:
            - integer
            - 'null'
        inbound_phone_number_data:
          type:
            - string
            - 'null'
        metrics:
          type: array
          items:
            type: integer
          description: Metric IDs applied to the scenario.
        metric_names:
          type: array
          items:
            type: string
        first_message:
          type: string
          description: First message the simulated caller speaks or sends.
        tool_ids:
          type: array
          items:
            type: string
        test_profile:
          type:
            - integer
            - 'null'
        test_profile_data:
          type:
            - object
            - 'null'
          properties:
            id:
              type: integer
            project:
              type:
                - integer
                - 'null'
            agent:
              type:
                - integer
                - 'null'
            name:
              type: string
            information:
              type:
                - object
                - 'null'
              additionalProperties:
                type: string
        dynamic_variable_values:
          type:
            - object
            - 'null'
          additionalProperties:
            type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        last_updated_by:
          type:
            - integer
            - 'null'
        folder_path:
          type:
            - string
            - 'null'
      required:
        - id
        - name
        - agent
        - created_at
        - updated_at
      example:
        id: 9512
        name: Refund escalation flow
        personality: 4643
        personality_name: Interruptive (High)
        phone_number: '+13125550188'
        expected_outcome_prompt: The assistant explains the refund policy and offers escalation.
        instructions: Call the support line and demand a refund for a damaged product.
        scenario_language: en
        scenario_type: workflow
        tags:
          - support
          - regression
        agent: 1259
        inbound_phone_number: null
        inbound_phone_number_data: null
        metrics:
          - 266881
          - 266882
        metric_names:
          - Greeting quality
          - Escalation quality
        first_message: Hi, I want a refund.
        tool_ids: []
        test_profile: null
        test_profile_data: null
        dynamic_variable_values: null
        created_at: '2026-10-13T18:04:05.123456Z'
        updated_at: '2026-10-13T18:04:05.123456Z'
        last_updated_by: 1
        folder_path: null
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````