> ## 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. # List issues > The agent's issues as its board shows them, Fix, Improve and Cause not established together, highest priority first, with any issue the live version fixed (`fellOnLive`: none of its calls shows it) after every one still happening: open ones, without consequences of another issue unless asked for. Only confirmed patterns are listed, and never what callers did that the agent could not have handled. A pattern whose cause is not established is listed with `section: "not_established"` and `causeEstablished: false`; it is not a Fix item and should be reported as a pattern whose cause is not established. These are listed after every Fix and Improve item, on every page, each group highest priority first. Anything else held back is found by id only, with `section: "hidden"` and the reason in `sectionNote`. Withdrawn issues (the analysis stopped producing them) are never listed. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/agents/{agentId}/issues openapi: 3.1.0 info: title: Signal API version: 1.0.0 description: >- Signal 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://first-signal-api.fly.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 Signal 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: get: tags: - Issues summary: List issues description: >- The agent's issues as its board shows them, Fix, Improve and Cause not established together, highest priority first, with any issue the live version fixed (`fellOnLive`: none of its calls shows it) after every one still happening: open ones, without consequences of another issue unless asked for. Only confirmed patterns are listed, and never what callers did that the agent could not have handled. A pattern whose cause is not established is listed with `section: "not_established"` and `causeEstablished: false`; it is not a Fix item and should be reported as a pattern whose cause is not established. These are listed after every Fix and Improve item, on every page, each group highest priority first. Anything else held back is found by id only, with `section: "hidden"` and the reason in `sectionNote`. Withdrawn issues (the analysis stopped producing them) are never listed. operationId: listIssues 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: integer minimum: 1 maximum: 100 default: 25 description: Items per page, 1 to 100. example: 25 required: false description: Items per page, 1 to 100. name: limit in: query - schema: type: string minLength: 1 description: '`nextCursor` from the previous page.' required: false description: '`nextCursor` from the previous page.' name: cursor in: query - schema: type: array items: type: string enum: - discovered - investigating - fix_deployed - measuring - resolved - regressed minItems: 1 description: >- Only these statuses, repeated or comma separated. When given, it is the whole status filter and `includeResolved` is not consulted. required: false description: >- Only these statuses, repeated or comma separated. When given, it is the whole status filter and `includeResolved` is not consulted. name: status in: query style: form explode: true - schema: type: array items: type: string enum: - technical - flow - content - behaviour minItems: 1 description: >- Only these classes, repeated or comma separated. Without it, every class the board shows. "behaviour" (what callers did that the agent could not have handled) is in neither section of the board, so asking for it lists nothing. required: false description: >- Only these classes, repeated or comma separated. Without it, every class the board shows. "behaviour" (what callers did that the agent could not have handled) is in neither section of the board, so asking for it lists nothing. name: klass in: query style: form explode: true - schema: type: string enum: - 'true' - 'false' default: 'false' description: >- Include resolved issues. Without `status`, resolved issues are left out, as on the board. required: false description: >- Include resolved issues. Without `status`, resolved issues are left out, as on the board. name: includeResolved in: query - schema: type: string enum: - 'true' - 'false' default: 'false' description: >- Include issues that are a consequence of another (`downstreamOf` set). Left out by default, as on the board, which shows them under the issue they follow from. required: false description: >- Include issues that are a consequence of another (`downstreamOf` set). Left out by default, as on the board, which shows them under the issue they follow from. name: includeDownstream in: query responses: '200': description: A page of issues. content: application/json: schema: $ref: '#/components/schemas/IssueList' '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://first-signal-api.fly.dev/v1/agents/6f1d2c3b-4a5e-4f60-8b7a-9c0d1e2f3a4b/issues?limit=10" \ -H "Authorization: Bearer $SIGNAL_API_KEY" components: schemas: IssueList: type: object properties: object: type: string enum: - list data: type: array items: $ref: '#/components/schemas/Issue' hasMore: type: boolean nextCursor: type: - string - 'null' description: Pass as `cursor` for the next page; null on the last page. required: - object - data - hasMore - nextCursor 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: test_calls description: analysed_calls, agents, copilot_messages or test_calls. limit: type: integer used: type: integer 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. 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 Signal 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 Signal 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", "fix_deployed", "measuring": set by a person in the web app as they work on 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. "regressed": it was resolved and a call after that showed it again. 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. `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.