> ## 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 an issue > One issue: where, why, what to change, how sure, how many evidence calls, how its calls split by version, the agent's grace period (`graceDays`) and whether the live version fixed it (`fix`), read with that grace period. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/agents/{agentId}/issues/{issueId} 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}/issues/{issueId}: get: tags: - Issues summary: Get an issue description: >- One issue: where, why, what to change, how sure, how many evidence calls, how its calls split by version, the agent's grace period (`graceDays`) and whether the live version fixed it (`fix`), read with that grace period. operationId: getIssue 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 issue's id. required: true description: The issue's id. name: issueId in: path responses: '200': description: The issue. content: application/json: schema: $ref: '#/components/schemas/IssueDetail' '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/issues/a2b3c4d5-e6f7-4a8b-9c0d-1e2f3a4b5c6d" \ -H "Authorization: Bearer $SIGNAL_API_KEY" components: schemas: IssueDetail: allOf: - $ref: '#/components/schemas/Issue' - type: object properties: evidenceCalls: type: integer description: >- Calls linked as evidence, listed by `GET .../issues/{issueId}/calls`. `byVersion` counts only the linked calls where the caller spoke, so its sum can be below this. byVersion: type: array items: type: object properties: version: type: - integer - 'null' description: Null for calls whose version is unknown. calls: type: integer description: >- This issue's evidence calls on the version where the caller spoke and the call was read. total: type: integer description: >- The agent's calls on the version where the caller spoke and the call was read, the same calls the web app's issue and version pages count. rate: type: number description: >- calls / total, 0 to 1. A drop on a newer version is a signal a fix landed, not proof. required: - version - calls - total - rate description: How the issue's calls split by version, newest first. graceDays: type: integer description: >- The agent's grace period in days (1 to 90, 7 by default): an open issue counts as resolved once the agent has taken calls for this long without it, and the live version is judged on an issue (`fix`) only once it has taken calls for this long. example: 7 fix: type: - object - 'null' properties: state: type: string enum: - fixed - fell - watching - no_change - rose - too_few description: >- "Did the fix work" on the live version. "fixed": no call on it shows the issue, and the drop is more than chance. "fell": it fell clearly but some calls still show it. "watching": the live version has run for less than the grace period, so it is too early to say. "no_change": no clear movement. "rose": it rose clearly. "too_few": too few calls to say. version: type: integer description: The live version. liveDays: type: integer description: >- Whole days the live version has taken calls, from its first call to the agent's newest. graceDays: type: integer description: The grace period the verdict was read with. text: type: string description: The verdict in one sentence, with the calls on each side. required: - state - version - liveDays - graceDays - text description: >- Whether the live version fixed this issue, against every earlier version, read with the grace period. Null when there is no live version or no calls before it. reopen: type: - object - 'null' properties: reason: type: string description: Why it reopened. Today always "Fix did not work". at: type: string format: date-time example: '2026-10-02T14:03:07.120Z' description: When the rate rule reopened it (the agent's clock). baseline: type: - object - 'null' properties: violated: type: integer decided: type: integer required: - violated - decided description: The pre-resolution rate the reopen was judged against. after: type: - object - 'null' properties: violated: type: integer decided: type: integer required: - violated - decided description: >- The rate on whole days after the resolution, at the moment of reopen. required: - reason - at - baseline - after description: >- Set when the issue was reopened because the rate after a resolution did not meaningfully drop ("Fix did not work"), with the baseline and after counts. Null or absent otherwise. The page prints the reason with those rates once resolved_at is cleared. required: - evidenceCalls - byVersion - graceDays - fix description: >- A problem worth fixing, named by a place, a cause (or "Cause not established" when nothing settled one) and a change. example: object: issue id: a2b3c4d5-e6f7-4a8b-9c0d-1e2f3a4b5c6d key: tool_timeout:check_availability code: tool_timeout title: The agent did not reply in Book appointment klass: technical lane: null status: discovered source: detector countOnly: false location: kind: tool id: check_availability label: check_availability cause: code: tool_latency label: The availability lookup takes longer than the caller waits detail: >- check_availability answered after 9.4 s at the median on these calls; callers spoke again or hung up before it returned. causeEstablished: true causeSummary: The availability lookup takes longer than the caller waits section: fix sectionNote: null target: kind: tool id: check_availability label: check_availability symptoms: - code: dead_air label: Silence while a tool runs count: 15 intentSlug: book_appointment likelyCause: null recommendation: >- Cache the next seven days of openings, or have the agent say it is checking before the lookup starts. volume: 15 rate: 0.03 failedOutcomeShare: 0.8 impact: high confidence: 0.86 priorityScore: 41.2 downstreamOf: null consequences: [] firstSeenVersion: 6 lastSeenVersion: 8 fellOnLive: false diagnosis: null createdAt: '2026-09-12T10:01:44.000Z' updatedAt: '2026-10-02T08:30:12.000Z' evidenceCalls: 15 byVersion: - version: 7 calls: 9 total: 180 rate: 0.05 - version: 8 calls: 6 total: 178 rate: 0.0337 graceDays: 7 fix: state: no_change version: 8 liveDays: 10 graceDays: 7 text: >- No change on v8 beyond noise: 6 of 178 on v8, against 9 of 180 before, over 10 days. 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 Issue: type: object properties: object: type: string enum: - issue id: 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 key: type: string description: >- Stable across re-analysis: the same problem at the same place keeps its key, so an issue can be followed from discovered to resolved. code: type: string description: >- What kind of problem it is: a signal code, or `outcome.` for an outcome issue. title: type: string klass: $ref: '#/components/schemas/IssueClass' lane: $ref: '#/components/schemas/Lane' status: $ref: '#/components/schemas/IssueStatus' source: type: string enum: - detector - outcome description: >- Which kind of finding this is, "detector" or "outcome". Some fields are set for only one kind, as their descriptions say. An agent's board shows one kind. countOnly: type: boolean description: >- True for a count of calls that ended badly at one step with no cause established. Not a finding: the board lists these apart, under "Cause not established", and never ranks them among the issues. location: $ref: '#/components/schemas/Location' cause: type: - object - 'null' properties: code: type: - string - 'null' description: A stable cause key; null for an outcome issue. label: type: string description: The cause as a person reads it. detail: type: - string - 'null' description: What in the trace says so. required: - code - label - detail description: >- Why it happens, taken from what the trace shows. A hypothesis until a change proves it. Null when no cause was established; read it with `causeEstablished`. causeEstablished: type: boolean description: >- Whether SignalMD established a cause. When false, say "cause not established": `likelyCause` reads that too, and no cause should be supplied in its place. The board prints it as a result, not a gap to fill. causeSummary: type: string description: >- One line on the cause, safe to repeat: the cause's label when it was established, otherwise "Cause not established." example: Cause not established. section: type: string enum: - fix - improve - not_established - hidden description: >- Which section of the board the issue is in. "fix": a confirmed defect with an established cause, in the agent or outside it (then `sectionNote` says the fix belongs to whoever runs the failing service or platform, and that a change in the agent can at most soften it for callers). "improve": a change the customer controls (a prompt, flow, routing or tool setting) that moves a board metric, with the change and the metric in `sectionNote`. "not_established": a confirmed pattern whose cause is not established; the board lists it under "Cause not established", `causeEstablished` is false, `sectionNote` starts "Cause not established", and `recommendation` is what to check, never a change. Present it as a pattern whose cause is not established, never as a defect to fix, and never count it among the Fix items. Listings hold these three. Fetched by id, anything else reads "hidden" and should not be presented as a finding: an issue too small to be a confirmed pattern, a consequence folded under the issue that caused it (`downstreamOf` set), or what callers did that the agent could not have handled (`klass` "behaviour"). example: fix sectionNote: type: - string - 'null' description: >- One sentence when the section needs it: a cause outside the agent and who has its fix, the change a lever is and the metric it moves, why the cause is not established, or why the issue is hidden. Null otherwise. example: null target: type: - object - 'null' properties: kind: type: string description: >- What gets changed: "tool", "step", "wording", "agent", "data" or "change". id: type: string label: type: string required: - kind - id - label description: >- The thing someone would change to make it stop. Issues are grouped on this: one change, one issue. symptoms: type: array items: type: object properties: code: type: string label: type: string count: type: integer required: - code - label - count description: >- How it was noticed, with how many calls showed each; one cause can surface more than one way. Outcome issues list their bad outcomes here. intentSlug: type: - string - 'null' description: What the callers wanted, when the issue is specific to one intent. likelyCause: type: - string - 'null' description: >- The issue page's cause line: a sentence or two, and a hypothesis, never a finding. Starts with "Cause not established" when `causeEstablished` is false, and then keeps only what was observed. recommendation: type: - string - 'null' description: >- The suggested fix. Null on a count row, where there is no cause to fix. volume: type: integer description: >- Calls affected. For an outcome issue, only calls where the cause was confirmed. rate: type: number description: Share of all analysed calls affected, 0 to 1. failedOutcomeShare: type: number description: >- Share of the affected calls that ended badly, 0 to 1. For an outcome issue, the share whose outcome outlasts the call (wrong details saved, nothing booked). impact: type: string enum: - low - medium - high confidence: type: number description: >- How sure SignalMD is that the issue is real and its cause right, 0 to 1. Not a measured probability: use it to compare issues, and read `causeEstablished` for whether there is a cause. priorityScore: type: number description: The board's rank, by impact. Higher first. downstreamOf: type: - string - 'null' description: >- The `key` of the issue this one follows from. Set means it is a consequence, not a separate thing to fix. Listed only with `includeDownstream=true`. consequences: type: array items: type: object properties: key: type: string title: type: string volume: type: integer required: - key - title - volume description: >- Issues that follow from this one, most affected first. Fixing this one is expected to clear them. firstSeenVersion: type: - integer - 'null' description: >- The oldest version the issue's calls ran on. Null for outcome issues, which do not record it; see `byVersion` on the issue. lastSeenVersion: type: - integer - 'null' description: >- The newest version the issue's calls ran on. Null for outcome issues. fellOnLive: type: boolean description: >- The live version fixed this issue: none of its calls shows it, judged only once that version has taken calls for the agent's grace period. Lists put such issues after every issue still happening, keeping the priority order within each group, as the board does. An issue that fell on the live version but is still seen on it is false here and keeps its place. diagnosis: $ref: '#/components/schemas/IssueDiagnosis' createdAt: type: string format: date-time example: '2026-10-02T14:03:07.120Z' updatedAt: type: string format: date-time example: '2026-10-02T14:03:07.120Z' required: - object - id - key - code - title - klass - lane - status - source - countOnly - location - cause - causeEstablished - causeSummary - section - sectionNote - target - symptoms - intentSlug - likelyCause - recommendation - volume - rate - failedOutcomeShare - impact - confidence - priorityScore - downstreamOf - consequences - firstSeenVersion - lastSeenVersion - fellOnLive - diagnosis - createdAt - updatedAt description: >- A problem worth fixing, named by a place, a cause (or "Cause not established" when nothing settled one) and a change. example: object: issue id: a2b3c4d5-e6f7-4a8b-9c0d-1e2f3a4b5c6d key: tool_timeout:check_availability code: tool_timeout title: The agent did not reply in Book appointment klass: technical lane: null status: discovered source: detector countOnly: false location: kind: tool id: check_availability label: check_availability cause: code: tool_latency label: The availability lookup takes longer than the caller waits detail: >- check_availability answered after 9.4 s at the median on these calls; callers spoke again or hung up before it returned. causeEstablished: true causeSummary: The availability lookup takes longer than the caller waits section: fix sectionNote: null target: kind: tool id: check_availability label: check_availability symptoms: - code: dead_air label: Silence while a tool runs count: 15 intentSlug: book_appointment likelyCause: null recommendation: >- Cache the next seven days of openings, or have the agent say it is checking before the lookup starts. volume: 15 rate: 0.03 failedOutcomeShare: 0.8 impact: high confidence: 0.86 priorityScore: 41.2 downstreamOf: null consequences: [] firstSeenVersion: 6 lastSeenVersion: 8 fellOnLive: false diagnosis: null createdAt: '2026-09-12T10:01:44.000Z' updatedAt: '2026-10-02T08:30:12.000Z' ErrorType: type: string enum: - invalid_request_error - authentication_error - budget_error - permission_error - not_found_error - conflict_error - rate_limit_error - api_error IssueClass: type: string enum: - technical - flow - content - behaviour description: >- Who a fix goes to. "technical": a tool, latency or platform defect, for an engineer. "flow": conversation design (routing, loops, confirmation handling). "content": prompts and knowledge (what the agent knows and says). "behaviour": something callers do that is worth knowing but is not a defect, so it is never counted among the problems. Lane: type: - string - 'null' enum: - hearing - understanding - flow - speaking - integrations - null description: >- The lane a fix belongs in, the one the board groups it under. Null where no lane fits, such as a call ending with no cause behind it. IssueStatus: type: string enum: - discovered - investigating - fix_deployed - measuring - resolved - regressed description: >- Where the issue stands. "discovered": found by the analysis. "investigating": set by a person in the web app. "fix_deployed": a fix is live, marked by a person or read from the live version's configuration change at the issue's step or tool. "measuring": a fix is live and the live version has too few calls, or has not run for the grace period, to judge it. "resolved": not seen on any call for a grace period (7 days unless set per agent), marked resolved by a person, or rejected as not a real problem; a later sighting alone does not reopen it, and too few calls or no baseline keep it resolved ("Not enough calls to tell yet"). "regressed": it was resolved and its rate since then rose clearly over the rate before it. When the rate is back at about the old one, SignalMD reopens the issue (not as regressed) with "Fix did not work". An issue with no rate from before never regresses. Location: type: - object - 'null' properties: kind: type: string enum: - node - edge - tool - global description: >- "node" is a step of the flow, "edge" a transition between two steps, "tool" a function the agent calls, "global" the whole call (no one place). id: type: string description: >- The step id, `from->to` for a transition, the tool's name, or `global`. label: type: string description: >- How it reads to a person: the step's name, `From → To`, the tool's name, or `Whole call`. required: - kind - id - label description: Where it happens. IssueDiagnosis: type: - object - 'null' properties: lane: allOf: - $ref: '#/components/schemas/Lane' - description: >- The lane a defect lives in, and so the kind of change that fixes it. "hearing": what the caller said versus what was recorded. "understanding": what the model did with what it received. "flow": what the configured graph did with what was understood (flow and state). "speaking": what the caller heard (latency, talking over, cut-off speech). "integrations": tools and knowledge bases. laneLabel: type: string example: Flow and state place: type: object properties: kind: type: string enum: - step - tool name: type: string description: >- The step's name or the tool's name, as the agent's configuration names it. required: - kind - name description: >- Where the change goes: the step the calls went wrong in, or the tool an integration fix belongs to. verdict: type: string enum: - defect - improvement description: >- "defect": something is broken. "improvement": nothing is broken, but a change would make these calls go better. established: type: boolean description: >- Whether a cause was established. False only on a count row: the cause was not established on any call, and nothing here should be read as the reason. verifiedCalls: type: integer description: >- Calls where the cause was confirmed. Only these are the issue's calls, its volume and its evidence. notEstablishedCalls: type: integer description: >- Calls that ended badly at the same place where the cause was not confirmed. Counted here, never listed as evidence. outcomes: type: array items: type: object properties: slug: type: string enum: - left_without - hung_up_mid_task - wrong_saved - repeated_themselves - not_compliant - time_wasted - caller_upset - not_helped_not_redirected - lost_sale - unusable_lead - unnecessary_handoff - overpromised - off_brand - kept_going description: The bad outcome. label: type: string example: Left without what they came for count: type: integer description: >- Calls with this outcome. One call can count under more than one. required: - slug - label - count description: >- What went wrong for callers or the company on these calls, most common first. check: type: object properties: kind: type: string enum: - tool_empty - stored_differs - said_not_done - question_repeated - caller_repeated - slow_reply - readback_differs - caller_unanswered - step_loop - outside_hours - signal - none label: type: string required: - kind - label description: >- The kind of evidence the cause rests on, with a label in plain words. `none` means the call record can neither confirm nor contradict it. cause: type: - string - 'null' description: >- The cause in technical terms. Null on a count row, where none was established. change: type: - string - 'null' description: The change someone could make, one sentence, in technical terms. changeShort: type: - string - 'null' description: The change in a few words. naming: type: - object - 'null' properties: title: type: string summary: type: string description: The issue in plain words for the agent's owner. fix: type: string description: The suggested fix in plain words. required: - title - summary - fix description: Plain-language wording for the issue. Null when none is available. required: - lane - laneLabel - place - verdict - established - verifiedCalls - notEstablishedCalls - outcomes - check - cause - change - changeShort - naming description: The diagnosis of an outcome issue. Null on detector issues. 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.