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

# Trigger a test run

> Trigger a simulation test run. Select test cases explicitly by id, by severity, or by tag via the `select` field. The legacy flat `testCaseIds` body is deprecated but still accepted.



## OpenAPI

````yaml api-reference/agents/openapi.json POST /v1/agents/{agentId}/testing/test-runs/trigger
openapi: 3.1.0
info:
  title: PolyAI Agents API
  version: 1.0.11
  description: Manage PolyAI agents, telephony, deployments, and real-time configs.
servers:
  - url: https://api.us.poly.ai
    description: US region
  - url: https://api.eu.poly.ai
    description: EU region
  - url: https://api.uk.poly.ai
    description: UK region
  - url: https://api.studio.poly.ai
    description: Studio region
security:
  - polyApiKey: []
paths:
  /v1/agents/{agentId}/testing/test-runs/trigger:
    parameters:
      - name: agentId
        in: path
        required: true
        schema:
          type: string
    post:
      tags:
        - Testing
      summary: Trigger a test run
      description: >-
        Trigger a simulation test run. Select test cases explicitly by id, by
        severity, or by tag via the `select` field. The legacy flat
        `testCaseIds` body is deprecated but still accepted.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerTestRunBody'
      responses:
        '200':
          description: Test run created
components:
  schemas:
    TriggerTestRunBody:
      type: object
      title: TriggerTestRunBody
      description: >-
        Selection criteria for which test cases to run in a triggered test run,
        by id, severity, or tag.
      properties:
        branchId:
          type: string
        select:
          anyOf:
            - type: object
              title: By test case ID
              properties:
                mode:
                  type: string
                  enum:
                    - testIds
                testIds:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 1000
              required:
                - mode
                - testIds
              additionalProperties: false
            - type: object
              title: By severity
              properties:
                mode:
                  type: string
                  enum:
                    - severities
                severities:
                  type: array
                  items:
                    type: string
                    enum:
                      - low
                      - medium
                      - high
                      - critical
                  minItems: 1
              required:
                - mode
                - severities
              additionalProperties: false
            - type: object
              title: By tag
              properties:
                mode:
                  type: string
                  enum:
                    - tags
                tags:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 50
              required:
                - mode
                - tags
              additionalProperties: false
        name:
          type: string
          minLength: 1
          maxLength: 120
      required:
        - branchId
        - select
      additionalProperties: false
  securitySchemes:
    polyApiKey:
      type: apiKey
      in: header
      name: X-API-KEY

````