> ## Documentation Index > Fetch the complete documentation index at: https://docs.egma.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a run > Run every active test in a suite against one agent connection. Execution and grading continue after this request returns. Keep the returned id to follow progress and inspect results. ## OpenAPI ````yaml openapi.json POST /v1/runs openapi: 3.1.0 info: title: Egma Platform API version: 1.0.0 description: >- The customer-facing HTTP interface used by Egma's web app, CLI, and outside clients. servers: - url: https://app.egma.ai security: [] paths: /v1/runs: post: tags: - Runs summary: Create a run description: >- Run every active test in a suite against one agent connection. Execution and grading continue after this request returns. Keep the returned id to follow progress and inspect results. operationId: createRun parameters: - name: projectId in: query required: false schema: type: string minLength: 1 description: >- Project to act in. A project-scoped API key already identifies its project. requestBody: required: true content: application/json: schema: type: object properties: suiteId: type: string minLength: 1 description: >- The active, non-empty test suite to execute in full. It must belong to the selected project. examples: - ste_01M0E4J0BBE1FVDVTZ1BSS5C97 agentId: type: string minLength: 1 description: >- The Egma agent to test, not its Retell provider ID or LiveKit dispatch name. examples: - agt_01M0E4J0BBE1FVDVTZ1BSS5C97 connectionId: type: string minLength: 1 description: >- An active connection on that agent in the same project. Its modality determines whether simulations use voice or chat. examples: - con_01M0E4J0BBE1FVDVTZ1BSS5C97 name: type: string description: Optional display name for the run. examples: - Appointment booking release check expectedTestVersions: type: array items: type: object properties: testId: type: string minLength: 1 description: The test identity to check. versionId: type: string minLength: 1 description: The current test version expected at run creation. required: - testId - versionId additionalProperties: false description: >- Optional exact list of the suite's test IDs and current version IDs. Each test and version must appear once. The request is refused if the suite membership or any version changed. Omit this field to use the current suite. required: - suiteId - agentId - connectionId additionalProperties: false examples: - suiteId: ste_01M0E4J0BBE1FVDVTZ1BSS5C97 agentId: agt_01M0E4J0BBE1FVDVTZ1BSS5C97 connectionId: con_01M0E4J0BBE1FVDVTZ1BSS5C97 name: Appointment booking release check responses: '201': description: >- The run header for a new request or an idempotent replay. The run may still be executing or grading. content: application/json: schema: type: object properties: id: type: string minLength: 1 projectId: type: string minLength: 1 suiteId: type: string minLength: 1 suiteName: type: string suiteDeleted: type: boolean name: anyOf: - type: string - type: 'null' status: type: string enum: - pending - running - completed - canceled description: >- Simulation execution status. A completed run can contain failed simulations, and grading may still be in progress. agentId: type: string minLength: 1 connectionId: type: string minLength: 1 connectionName: anyOf: - type: string - type: 'null' agentPlatform: anyOf: - type: string - type: 'null' connectionType: type: string accessVariant: type: string modality: type: string enum: - voice - chat productLabel: type: string environment: anyOf: - type: string - type: 'null' agentVersion: anyOf: - type: integer - type: 'null' expectedSimulationCount: type: integer description: >- Number of test-and-persona combinations captured when the run started. completedCount: anyOf: - type: integer - type: 'null' failedCount: anyOf: - type: integer - type: 'null' canceledCount: anyOf: - type: integer - type: 'null' simulationCounts: type: object properties: queued: type: integer claimed: type: integer running: type: integer completed: type: integer failed: type: integer canceled: type: integer required: - queued - claimed - running - completed - failed - canceled additionalProperties: false finishedCount: type: integer description: >- Simulations whose execution completed, failed, or was canceled. gradableCount: type: integer description: >- Simulations eligible for grading under the run's frozen grader selection. gradedCount: type: integer description: >- Gradable simulations whose grading is complete or errored. This is not a count of passed simulations. resultsUrl: type: string description: >- Open this URL in a browser to follow the run and inspect its results. createdAt: type: string format: date-time startedAt: anyOf: - type: string format: date-time - type: 'null' finishedAt: anyOf: - type: string format: date-time - type: 'null' required: - id - projectId - suiteId - suiteName - suiteDeleted - name - status - agentId - connectionId - connectionName - agentPlatform - connectionType - accessVariant - modality - productLabel - environment - agentVersion - expectedSimulationCount - completedCount - failedCount - canceledCount - simulationCounts - finishedCount - gradableCount - gradedCount - resultsUrl - createdAt - startedAt - finishedAt additionalProperties: false '400': description: The request was refused. content: application/json: schema: $ref: '#/components/schemas/Refusal' '401': description: The request was refused. content: application/json: schema: $ref: '#/components/schemas/Refusal' '403': description: The request was refused. content: application/json: schema: $ref: '#/components/schemas/Refusal' '404': description: The request was refused. content: application/json: schema: $ref: '#/components/schemas/Refusal' '409': description: The request was refused. content: application/json: schema: $ref: '#/components/schemas/Refusal' '422': description: The request was refused. content: application/json: schema: $ref: '#/components/schemas/Refusal' '429': description: The request rate limit was reached. headers: Retry-After: description: Seconds to wait before trying again. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/Refusal' '503': description: The request was refused. content: application/json: schema: $ref: '#/components/schemas/Refusal' security: - bearerAuth: [] - sessionCookie: [] components: schemas: Refusal: type: object properties: error: type: string message: type: string details: type: object additionalProperties: true required: - error - message additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer description: An Egma API key. sessionCookie: type: apiKey in: cookie name: egma.session_token description: >- The browser session cookie issued by Egma. HTTPS deployments add the standard __Secure- prefix. ````