> ## 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 trace ## OpenAPI ````yaml openapi.json GET /v1/traces/{traceId} 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/traces/{traceId}: get: tags: - Traces summary: Get a trace operationId: getTrace parameters: - name: traceId in: path required: true schema: type: string - name: from in: query required: true schema: type: string format: date-time - name: to in: query required: true schema: type: string format: date-time - name: projectId in: query required: false schema: type: string minLength: 1 responses: '200': description: The trace and its grades. content: application/json: schema: type: object properties: trace: 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 source: type: string enum: - simulation - production pov: type: string enum: - persona - agent description: >- The trace's primary source: agent for the agent's own evidence, or persona for Egma's simulated caller. A simulation can contain spans from both sources; each span has its own pov. environment: type: string connectionType: type: string providerCallId: type: string agentPlatform: type: string platformAgentId: type: string platformAgentName: type: string platformAgentVersion: type: string runId: type: string agentId: type: string required: - traceId - startedAt - endedAt - durationNs - spanCount - turnCounts - toolSpanCount - erroredSpanCount - source - pov - environment - connectionType - providerCallId - agentPlatform - platformAgentId - platformAgentName - platformAgentVersion - runId - agentId additionalProperties: false turns: type: array items: $ref: '#/components/schemas/traceSpan' spans: type: array items: $ref: '#/components/schemas/traceSpan' spansTruncated: type: boolean 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 simulationId: anyOf: - type: string minLength: 1 - type: 'null' gradingState: type: string enum: - not_requested - pending - running - complete - error workBlock: anyOf: - type: object properties: error: type: string enum: - allowance_spent - providers_unfunded 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. required: - trace - turns - spans - spansTruncated - metrics - simulationId - gradingState - workBlock - grades - gradeHistory - combinedScore 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. ````