> ## 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 runs > Test runs of this agent, newest first, each with its progress, cost and summary. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/agents/{agentId}/runs 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}/runs: get: tags: - Runs summary: List runs description: >- Test runs of this agent, newest first, each with its progress, cost and summary. operationId: listRuns 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: string enum: - queued - awaiting_approval - running - complete - refused - failed description: Only runs with this status. required: false description: Only runs with this status. name: status in: query - schema: type: - integer - 'null' minimum: 0 description: Only runs of this agent version. required: false description: Only runs of this agent version. name: version in: query - 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: Only runs of this test set. required: false description: Only runs of this test set. name: testSetId in: query responses: '200': description: A page of runs. content: application/json: schema: $ref: '#/components/schemas/RunList' '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/runs?status=complete" \ -H "Authorization: Bearer $SIGNAL_API_KEY" components: schemas: RunList: type: object properties: object: type: string enum: - list data: type: array items: $ref: '#/components/schemas/Run' 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 Run: type: object properties: object: type: string enum: - run 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 status: type: string enum: - queued - awaiting_approval - running - complete - refused - failed description: >- queued, running, then complete, refused (budget) or failed. An automatic run over the budget waits in awaiting_approval for a person. message: type: - string - 'null' description: >- The latest status message: what the budget covered, or why it refused or failed. kind: type: string enum: - run - calibration description: >- A calibration run plays each test 3 times to decide whether it gates. trigger: type: - string - 'null' enum: - manual - auto - ci - null description: 'Who started it: a person, Signal on a new version, or an API key.' version: type: integer description: The agent version played. testSetId: type: - string - 'null' 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 testIds: type: array items: 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 tests requested, in order. personas: type: - array - 'null' items: type: string description: The personas requested; null means each test's own caller. repeats: anyOf: - type: number enum: - 3 - type: 'null' description: '3: every cell runs three times and reports k of 3.' shadowAgentId: type: - string - 'null' 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: Set when the run played a shadow copy of the version. progress: type: object properties: completed: type: integer description: Cells finished. total: type: - integer - 'null' description: >- Cells to play: every requested cell until the budget is reserved, then the cells it covers. required: - completed - total description: Cells finished of cells to play. cells: type: object properties: requested: type: integer runnable: type: - integer - 'null' description: >- Cells the budget let through, a prefix of the request. Null until the budget is reserved. required: - requested - runnable description: >- Fewer runnable than requested means the budget covered part of the run; the rest are not run. summary: $ref: '#/components/schemas/RunSummary' cost: type: object properties: retellUsd: type: number description: >- The customer's Retell spend: reserved while running, then the estimate for what ran. What the budget caps. signalUsd: type: number description: Signal's own cost. Never counted against the budget. required: - retellUsd - signalUsd description: Estimated spend. approvedAt: type: - string - 'null' format: date-time example: '2026-10-02T14:03:07.120Z' description: When a person approved an automatic run that was over the budget. createdBy: type: - string - 'null' description: 'Who started it: a user id, or key: for an API key.' 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 - status - message - kind - trigger - version - testSetId - testIds - personas - repeats - shadowAgentId - progress - cells - summary - cost - approvedAt - createdBy - createdAt - updatedAt example: object: run id: d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a status: complete message: null kind: run trigger: ci version: 8 testSetId: c7d8e9f0-a1b2-4c3d-8e4f-5a6b7c8d9e0f testIds: - 3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f personas: null repeats: null shadowAgentId: null progress: completed: 12 total: 12 cells: requested: 12 runnable: 12 summary: cells: 12 scored: 12 counts: passed: 9 failed: 2 flaky: 1 error: 0 drift: 0 notRun: 0 passRate: 0.75 cost: retellUsd: 1.84 signalUsd: 0.21 approvedAt: null createdBy: key:00000000-0000-4000-8000-00000000000a createdAt: '2026-10-02T11:00:03.000Z' updatedAt: '2026-10-02T11:07:41.000Z' ErrorType: type: string enum: - invalid_request_error - authentication_error - budget_error - permission_error - not_found_error - conflict_error - rate_limit_error - api_error RunSummary: type: object properties: cells: type: integer description: Tests times personas. scored: type: integer description: Cells with a result. counts: $ref: '#/components/schemas/RunCellCounts' passRate: type: - number - 'null' description: >- Passed over scored; flaky and error count against it. Null when nothing was scored. gating: type: object properties: cells: type: integer counts: $ref: '#/components/schemas/RunCellCounts' required: - cells - counts description: >- The same over cells whose test is calibrated, which alone say anything about a release. On GET .../runs/{runId} only. required: - cells - scored - counts - passRate example: cells: 12 scored: 12 counts: passed: 9 failed: 2 flaky: 1 error: 0 drift: 0 notRun: 0 passRate: 0.75 RunCellCounts: type: object properties: passed: type: integer failed: type: integer flaky: type: integer error: type: integer drift: type: integer description: >- The simulated caller left its script, so the attempt says nothing about the agent. notRun: type: integer description: Not run (budget, phone tier) or still running. required: - passed - failed - flaky - error - drift - notRun 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.