> ## Documentation Index > Fetch the complete documentation index at: https://docs.signalmd.dev/llms.txt > Use this file to discover all available pages before exploring further. # Get a call's trace > The call as SignalMD reads it: turns, tool calls, the path through the flow, latency by layer, and measurements. Facts the platform recorded, with none of its own judgements. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/agents/{agentId}/calls/{callId}/trace openapi: 3.1.0 info: title: SignalMD API version: 1.0.0 description: >- SignalMD reads a voice agent's production calls and says what to fix, then tests whether the fix worked. This API exposes the same data the web app shows: agents, calls and their traces, signals, issues, versions and their comparisons, tests, and test runs. Authenticate with `Authorization: Bearer sig_...` (an API key from the API keys page). Read keys may call every `read` operation; write keys may also call `write` operations, within their monthly budget. Each operation's scope is in `x-signal-scope`. Errors share one envelope (`Error`), lists share one cursor scheme (`limit`, `cursor`, `hasMore`, `nextCursor`), and every response carries `Request-Id` and `RateLimit-*` headers. servers: - url: https://api.signalmd.dev description: Production - url: http://localhost:43124 description: Local development security: - bearerAuth: [] tags: - name: Account description: Who the token belongs to and what it may do. - name: Agents description: Voice agents connected to the workspace. - name: Calls description: Production calls, their traces and per-call signals. - name: Signals description: What SignalMD noticed across calls. - name: Issues description: 'Problems worth fixing: where, why, and what to change.' - name: Versions description: Agent versions and how each one did. - name: Comparisons description: Stored comparisons between two versions. - name: Tests description: Tests, test sets, personas and coverage. - name: Runs description: Test runs and the attempts inside them. paths: /v1/agents/{agentId}/calls/{callId}/trace: get: tags: - Calls summary: Get a call's trace description: >- The call as SignalMD reads it: turns, tool calls, the path through the flow, latency by layer, and measurements. Facts the platform recorded, with none of its own judgements. operationId: getCallTrace parameters: - schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ example: 3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f description: The agent's id. required: true description: The agent's id. name: agentId in: path - schema: type: string format: uuid description: The call's id in SignalMD (not the platform's call id). required: true description: The call's id in SignalMD (not the platform's call id). name: callId in: path responses: '200': description: The trace. content: application/json: schema: $ref: '#/components/schemas/Trace' '400': description: 'Invalid request: a parameter or the body failed validation.' content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing, invalid or revoked credentials. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Not permitted for this principal. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- The agent, or a resource under it, does not exist or is not visible to this key. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limited. See Retry-After. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Server error. The message is generic; quote the request id. content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: bash label: curl source: >- curl "https://api.signalmd.dev/v1/agents/6f1d2c3b-4a5e-4f60-8b7a-9c0d1e2f3a4b/calls/0b9e8d7c-6f5a-4b3c-9d2e-1f0a9b8c7d6e/trace" \ -H "Authorization: Bearer $SIGNAL_API_KEY" components: schemas: Trace: type: object properties: object: type: string enum: - trace callId: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ example: 3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f description: The call's id in SignalMD. providerCallId: type: - string - 'null' version: type: - integer - 'null' direction: type: - string - 'null' status: type: - string - 'null' description: The platform's call status. startedAt: type: - string - 'null' format: date-time example: '2026-10-02T14:03:07.120Z' endedAt: type: - string - 'null' format: date-time example: '2026-10-02T14:03:07.120Z' durationMs: type: - number - 'null' disconnectionReason: type: - string - 'null' turns: type: array items: $ref: '#/components/schemas/TraceTurn' toolCalls: type: array items: $ref: '#/components/schemas/TraceToolCall' path: type: array items: $ref: '#/components/schemas/TraceNodeVisit' description: >- The flow steps the call went through, in order. A step visited twice appears twice. transitions: type: array items: type: object properties: from: type: string to: type: string kind: type: - string - 'null' required: - from - to - kind description: Each move between consecutive steps of `path`, by step id. latency: $ref: '#/components/schemas/TraceLatency' measures: type: object properties: turnCount: type: integer userTurnCount: type: integer agentTurnCount: type: integer agentWordShare: type: number description: Share of spoken words that were the agent's, 0 to 1. longestSilenceSec: type: number silenceCount: type: integer agentRepeatCount: type: integer userRepeatCount: type: integer userCorrectionCount: type: integer description: Caller turns that read as correcting what the agent understood. nodeRevisitMax: type: integer description: Most visits to any one step. distinctNodeCount: type: integer toolCallCount: type: integer toolFailureCount: type: integer required: - turnCount - userTurnCount - agentTurnCount - agentWordShare - longestSilenceSec - silenceCount - agentRepeatCount - userRepeatCount - userCorrectionCount - nodeRevisitMax - distinctNodeCount - toolCallCount - toolFailureCount description: >- Measurements of the conversation. Counts, not findings: whether any of them is a problem is for the issues to say. platform: type: object properties: collectedVariables: type: - object - 'null' additionalProperties: {} description: >- Values the agent stored during the call, as the platform recorded them. Can hold what the caller said. givenVariables: type: - object - 'null' additionalProperties: {} description: >- Values the call was handed before it started (a customer record, the local time), as the platform recorded them. transcript: type: - string - 'null' description: The platform's plain text transcript. required: - collectedVariables - givenVariables - transcript description: >- What the platform recorded, never what it concluded: the platform's own summary, sentiment and success flag are not included. No link to the call's audio is given: the recording stays with the platform. required: - object - callId - providerCallId - version - direction - status - startedAt - endedAt - durationMs - disconnectionReason - turns - toolCalls - path - transitions - latency - measures - platform Error: type: object properties: error: type: object properties: type: $ref: '#/components/schemas/ErrorType' code: type: string example: agent_not_found description: The specific reason; stable within v1. message: type: string example: Agent not found. param: type: - string - 'null' description: The request field at fault, for a validation error. requestId: type: - string - 'null' example: req_8c1f0e2b4a6d9e3f7a5c1b0d quota: type: object properties: metric: type: string example: credits description: >- credits when the workspace's monthly credits are used up, or agents when the plan's agent limit is reached. activity: type: string enum: - observation - testing - chat example: testing description: >- With metric credits: what the request would have spent them on. observation is analysing calls, testing is test runs, chat is the copilot. requested: type: integer example: 18 description: >- With metric credits: the credits the request needed to start. limit: type: integer description: 'The plan''s limit: the month''s credits, or its agents.' used: type: integer description: How much of the limit is used this month. plan: type: string example: free_org description: The workspace's plan slug. upgradePath: type: string example: /billing description: Where in the web app the plan is changed. required: - metric - limit - used - plan - upgradePath description: >- Present when code is quota_exceeded: the plan limit the request would pass. proposalId: type: string format: uuid description: >- Present when code is criteria_locked: the pending criteria proposal the change was filed as. A person approves or rejects it. required: - type - code - message - param - requestId required: - error example: error: type: not_found_error code: agent_not_found message: Agent not found. param: null requestId: req_8c1f0e2b4a6d9e3f7a5c1b0d TraceTurn: type: object properties: index: type: integer role: type: string enum: - agent - user description: '`user` is the caller.' text: type: string noise: type: boolean description: 'On a caller turn: this text was not the caller speaking.' startSec: type: - number - 'null' description: Seconds from the start of the call. endSec: type: - number - 'null' nodeId: type: - string - 'null' description: The flow step the agent was in. nodeName: type: - string - 'null' required: - index - role - text - noise - startSec - endSec - nodeId - nodeName example: index: 7 role: agent text: Let me check what we have open next week. noise: false startSec: 41.2 endSec: 43.9 nodeId: node_book_appointment nodeName: Book appointment TraceToolCall: type: object properties: index: type: integer turnIndex: type: integer description: Index into `turns` of the utterance this tool call follows. name: type: string arguments: type: - string - 'null' description: The arguments as the platform recorded them, usually JSON text. result: type: - string - 'null' description: What the tool returned, as recorded. success: type: boolean failureKind: type: - string - 'null' enum: - error - timeout - empty - rejected - call_ended - null description: >- How it failed. `call_ended`: invoked and never answered because the call ended, which is what a tool that ends a call does by design. latencyMs: type: - number - 'null' startSec: type: - number - 'null' endSec: type: - number - 'null' nodeId: type: - string - 'null' required: - index - turnIndex - name - arguments - result - success - failureKind - latencyMs - startSec - endSec - nodeId example: index: 2 turnIndex: 7 name: check_availability arguments: '{"service":"cleaning","week":"2026-10-05"}' result: null success: false failureKind: timeout latencyMs: 9400 startSec: 43.9 endSec: 53.3 nodeId: node_book_appointment TraceNodeVisit: type: object properties: order: type: integer nodeId: type: string nodeName: type: string firstTurnIndex: type: integer turnCount: type: integer startSec: type: - number - 'null' endSec: type: - number - 'null' arrivedBy: type: - string - 'null' description: >- `normal`: followed the flow as drawn. `global`: something the caller said pulled the call out of the step it was in. Null when the platform did not say. required: - order - nodeId - nodeName - firstTurnIndex - turnCount - startSec - endSec - arrivedBy TraceLatency: type: object properties: e2eP50Ms: type: - number - 'null' description: >- Median time from the caller finishing to the agent starting to speak, in milliseconds. Null when the platform did not report it. e2eP90Ms: type: - number - 'null' description: >- 90th percentile of the same, in milliseconds. Null when the platform did not report it. e2eMaxMs: type: - number - 'null' description: >- Longest of the same, in milliseconds. Null when the platform did not report it. asrP50Ms: type: - number - 'null' description: >- Median time to turn what the caller said into text, in milliseconds. Null when the platform did not report it. llmP50Ms: type: - number - 'null' description: >- Median time to work out what to say, in milliseconds. Null when the platform did not report it. ttsP50Ms: type: - number - 'null' description: >- Median time to start saying it, in milliseconds. Null when the platform did not report it. knowledgeBaseP50Ms: type: - number - 'null' description: >- Median time to look something up in the knowledge base, in milliseconds. Null when the platform did not report it. required: - e2eP50Ms - e2eP90Ms - e2eMaxMs - asrP50Ms - llmP50Ms - ttsP50Ms - knowledgeBaseP50Ms ErrorType: type: string enum: - invalid_request_error - authentication_error - budget_error - permission_error - not_found_error - conflict_error - rate_limit_error - api_error securitySchemes: bearerAuth: type: http scheme: bearer description: An API key (`sig_...`), or a session token from the web app. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.