> ## 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.

# Get a run



## OpenAPI

````yaml openapi.json GET /v1/runs/{runId}
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/{runId}:
    get:
      tags:
        - Runs
      summary: Get a run
      operationId: getRun
      parameters:
        - name: runId
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            description: Run ID returned by Create a run or List runs.
            examples:
              - run_01M0E4J0BBE1FVDVTZ1BSS5C97
        - 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.
      responses:
        '200':
          description: The bounded run header and target context.
          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'
                  eventThrough:
                    type: integer
                  workBlock:
                    anyOf:
                      - type: object
                        properties:
                          error:
                            type: string
                            enum:
                              - allowance_spent
                              - providers_unfunded
                          message:
                            type: string
                        required:
                          - error
                          - message
                        additionalProperties: false
                      - type: 'null'
                  tempMockAgentVersion:
                    anyOf:
                      - type: integer
                      - type: 'null'
                  tempMockAgentVersionCleanup:
                    anyOf:
                      - type: boolean
                      - type: 'null'
                  mockMetadata:
                    anyOf:
                      - type: object
                        properties:
                          engine:
                            type: object
                            properties:
                              type:
                                type: string
                              engineId:
                                type: string
                              version:
                                anyOf:
                                  - type: integer
                                  - type: 'null'
                            required:
                              - type
                              - engineId
                              - version
                            additionalProperties: false
                        required:
                          - engine
                        additionalProperties: false
                      - type: 'null'
                  connectionSnapshot:
                    type: object
                    properties:
                      agentPlatform:
                        anyOf:
                          - type: string
                          - type: 'null'
                      connectionType:
                        type: string
                      accessVariant:
                        type: string
                      modality:
                        type: string
                        enum:
                          - voice
                          - chat
                      topology:
                        type: string
                      environment:
                        anyOf:
                          - type: string
                          - type: 'null'
                      config: {}
                    required:
                      - agentPlatform
                      - connectionType
                      - accessVariant
                      - modality
                      - topology
                      - environment
                      - config
                    additionalProperties: false
                  agent:
                    anyOf:
                      - type: object
                        properties:
                          id:
                            type: string
                            minLength: 1
                          name:
                            type: string
                          archived:
                            type: boolean
                        required:
                          - id
                          - name
                          - archived
                        additionalProperties: false
                      - type: 'null'
                  connection:
                    anyOf:
                      - type: object
                        properties:
                          id:
                            type: string
                            minLength: 1
                          name:
                            type: string
                          archived:
                            type: boolean
                          productLabel:
                            type: string
                        required:
                          - id
                          - name
                          - archived
                          - productLabel
                        additionalProperties: false
                      - 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
                  - eventThrough
                  - workBlock
                  - tempMockAgentVersion
                  - tempMockAgentVersionCleanup
                  - mockMetadata
                  - connectionSnapshot
                  - agent
                  - connection
                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'
        '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'
      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.

````