> ## 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 simulation > Read a simulation’s test, persona, connection, metrics, transcript, and grades. Execution status and gradingState are separate: a completed simulation may still be grading. ## OpenAPI ````yaml openapi.json GET /v1/simulations/{simulationId} 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/simulations/{simulationId}: get: tags: - Simulations summary: Get a simulation description: >- Read a simulation’s test, persona, connection, metrics, transcript, and grades. Execution status and gradingState are separate: a completed simulation may still be grading. operationId: getSimulation parameters: - name: simulationId in: path required: true schema: type: string minLength: 1 description: Simulation ID returned by List simulations in a run. examples: - sim_01M0E4J0BBE1FVDVTZ1BSS5C97 - name: projectId in: query required: false schema: type: string minLength: 1 responses: '200': description: >- The simulation and its available evidence. Check spansTruncated before treating the returned span tree as complete. content: application/json: schema: type: object properties: id: type: string minLength: 1 projectId: type: string minLength: 1 runId: type: string minLength: 1 runName: anyOf: - type: string - type: 'null' position: type: integer status: type: string enum: - queued - claimed - running - completed - failed - canceled workBlock: anyOf: - type: object properties: error: type: string enum: - allowance_spent - providers_unfunded message: type: string required: - error - message additionalProperties: false - type: 'null' gradingState: anyOf: - type: string enum: - not_requested - pending - running - complete - error - type: 'null' evidenceError: anyOf: - type: object properties: error: type: string const: evidence_collection_error message: type: string required: - error - message additionalProperties: false - type: 'null' grades: type: array items: type: object properties: projectGraderId: type: string minLength: 1 graderDefinitionId: type: string minLength: 1 graderDefinitionVersion: type: integer minimum: 1 parameterValues: type: object additionalProperties: true description: >- The model or numeric settings used for this grading attempt. Retained for successful and errored grades, including after temporary jobs are removed. Contains no credentials. graderName: type: string score: anyOf: - type: number minimum: 0 maximum: 1 - type: 'null' details: type: object properties: rationale: type: string assertions: type: array items: type: object properties: key: type: string decision: type: string enum: - met - not_met - cannot_determine score: type: number minimum: 0 maximum: 1 rationale: type: string citedSpanIds: type: array items: type: string citedTurns: type: array items: type: integer minimum: 1 error: type: string required: - key additionalProperties: false error: type: string additionalProperties: true passThreshold: type: number minimum: 0 maximum: 1 result: type: string enum: - passed - failed - errored gradedAt: type: string format: date-time required: - projectGraderId - graderDefinitionId - graderDefinitionVersion - parameterValues - graderName - score - details - passThreshold - result - gradedAt additionalProperties: false description: >- The current result for each selected grader. Each grade has its own score, frozen threshold, result, and supporting details. gradeHistory: type: array items: type: object properties: projectGraderId: type: string minLength: 1 graderDefinitionId: type: string minLength: 1 graderDefinitionVersion: type: integer minimum: 1 parameterValues: type: object additionalProperties: true description: >- The model or numeric settings used for this grading attempt. Retained for successful and errored grades, including after temporary jobs are removed. Contains no credentials. graderName: type: string score: anyOf: - type: number minimum: 0 maximum: 1 - type: 'null' details: type: object properties: rationale: type: string assertions: type: array items: type: object properties: key: type: string decision: type: string enum: - met - not_met - cannot_determine score: type: number minimum: 0 maximum: 1 rationale: type: string citedSpanIds: type: array items: type: string citedTurns: type: array items: type: integer minimum: 1 error: type: string required: - key additionalProperties: false error: type: string additionalProperties: true passThreshold: type: number minimum: 0 maximum: 1 result: type: string enum: - passed - failed - errored gradedAt: type: string format: date-time required: - projectGraderId - graderDefinitionId - graderDefinitionVersion - parameterValues - graderName - score - details - passThreshold - result - gradedAt additionalProperties: false description: >- Recorded grade results, including previous grading attempts. Regrading preserves this history. combinedScore: anyOf: - type: number minimum: 0 maximum: 1 - type: 'null' description: >- Display-only arithmetic mean when every selected grader has a current score. Null while a required score is missing or errored. This is not an overall pass/fail result. reason: anyOf: - type: string - type: 'null' executionFailure: anyOf: - type: string - type: 'null' modality: type: string enum: - voice - chat createdAt: type: string format: date-time startedAt: anyOf: - type: string format: date-time - type: 'null' endedAt: anyOf: - type: string format: date-time - type: 'null' providerReference: anyOf: - type: string - type: 'null' hasRecording: type: boolean agentPovComplete: type: boolean agentPovIncomplete: type: boolean measures: type: object properties: durationMs: type: integer turnCount: type: integer toolCallCount: type: integer erroredStepCount: type: integer humanTurnCount: type: integer agentTurnCount: type: integer additionalProperties: false metrics: type: array items: type: object description: >- One metric from one side of the conversation. Simulation metrics prefer the persona's series when available. Production traces use the agent's evidence. A second series stays separate in otherPov. properties: measure: type: string description: >- Metric identifier. turn_response_latency measures the wait from the end of the caller's turn to the agent's reply. For voice simulations, it runs from the end of the caller's played audio, including trailing padding, to the arrival of the agent's audio. first_response_latency measures the wait from conversation start to the first reply. Both use milliseconds. unit: type: string derived: type: boolean pov: type: string enum: - persona - agent description: >- The source of these measurements: agent for the agent's own evidence, or persona for Egma's simulated caller. The samples and summary values describe only this source. reportedBy: type: string samples: type: array items: type: number spanIds: type: array items: type: string mean: type: number p50: type: number p90: type: number partial: type: boolean otherPov: type: object properties: pov: type: string enum: - persona - agent derived: type: boolean reportedBy: type: string samples: type: array items: type: number spanIds: type: array items: type: string partial: type: boolean required: - pov - derived - samples - spanIds - partial additionalProperties: false description: >- The same metric measured from the other side of a simulation. Keep its samples separate from the primary series. Absent when only one side measured the conversation, including production traces. required: - measure - unit - derived - pov - samples - spanIds - mean - p50 - p90 - partial additionalProperties: false description: >- Observed facts about the conversation, such as latency and duration. Metrics are separate from grader results. test: type: object properties: id: type: string minLength: 1 versionId: type: string minLength: 1 name: anyOf: - type: string - type: 'null' scenario: anyOf: - type: string - type: 'null' expectedBehaviors: anyOf: - type: array items: type: string - type: 'null' required: - id - versionId - name - scenario - expectedBehaviors additionalProperties: false persona: type: object properties: id: type: string minLength: 1 name: anyOf: - type: string - type: 'null' versionId: type: string minLength: 1 identityName: anyOf: - type: string - type: 'null' personality: anyOf: - type: string - type: 'null' language: anyOf: - type: string - type: 'null' required: - id - name - versionId - identityName - personality - language additionalProperties: false agent: type: object properties: id: type: string minLength: 1 name: anyOf: - type: string - type: 'null' archived: anyOf: - type: boolean - type: 'null' required: - id - name - archived additionalProperties: false connection: type: object properties: id: type: string minLength: 1 name: anyOf: - type: string - type: 'null' archived: anyOf: - type: boolean - type: 'null' required: - id - name - archived additionalProperties: false 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 gradingPlan: anyOf: - type: object description: >- The grader definitions, versions, and pass thresholds frozen when the run started. Regrading uses this selection. properties: capturedAt: type: string format: date-time items: type: array items: type: object properties: projectGraderId: type: string minLength: 1 graderDefinitionId: type: string minLength: 1 graderDefinitionVersion: type: integer minimum: 1 graderName: type: string passThreshold: type: number minimum: 0 maximum: 1 required: - projectGraderId - graderDefinitionId - graderDefinitionVersion - graderName - passThreshold additionalProperties: false required: - capturedAt - items additionalProperties: false - type: 'null' transcript: anyOf: - type: object properties: traceId: type: string startedAt: type: string format: date-time endedAt: type: string format: date-time durationNs: type: string spanCount: type: integer turnCounts: type: object properties: human: type: integer agent: type: integer required: - human - agent additionalProperties: false toolSpanCount: type: integer erroredSpanCount: type: integer turns: type: array items: $ref: '#/components/schemas/traceSpan' spans: type: array items: $ref: '#/components/schemas/traceSpan' spansTruncated: type: boolean description: >- True when the response's span limit prevented the complete trace tree from being returned. required: - traceId - startedAt - endedAt - durationNs - spanCount - turnCounts - toolSpanCount - erroredSpanCount - turns - spans - spansTruncated additionalProperties: false - type: 'null' description: >- The conversation and tool evidence available for this simulation. Null when no trace is available. required: - id - projectId - runId - runName - position - status - gradingState - evidenceError - grades - gradeHistory - combinedScore - reason - executionFailure - workBlock - modality - createdAt - startedAt - endedAt - providerReference - hasRecording - agentPovComplete - agentPovIncomplete - measures - metrics - test - persona - agent - connection - connectionSnapshot - gradingPlan - transcript 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' '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: traceSpan: type: object properties: spanId: type: string parentSpanId: type: string name: type: string kind: type: string status: type: string startedAt: type: string format: date-time durationNs: type: string text: type: string audioUrl: type: string toolName: type: string toolArguments: type: string toolResult: type: string pov: type: string enum: - persona - agent description: >- Whose account this span records: agent for the agent’s own turns and tools, or persona for Egma’s caller. Read the agent spans for one transcript; combining both repeats the conversation. toolProvenance: type: string enum: - mocked description: >- Present when a mock with this toolName answered the call. Read from the simulation’s pinned test version. Absent on ordinary tool calls and production traces. spans: type: array items: $ref: '#/components/schemas/traceSpan' required: - spanId - parentSpanId - name - kind - status - startedAt - durationNs - text - audioUrl - toolName - toolArguments - toolResult - pov - spans additionalProperties: false 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. ````