> ## Documentation Index > Fetch the complete documentation index at: https://docs.guidinghand.ai/llms.txt > Use this file to discover all available pages before exploring further. # List test runs > Newest first. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/test_runs openapi: 3.1.0 info: title: GuidingHand API version: 1.0.0 description: >- Create sessions (an invite link with a code for the person at the computer), run tasks on their computer with one of your agents, follow them, answer their questions and approvals, and fetch history and recordings. Test your agents with evals: test cases on fresh machines, run in test sets, scored by a check script or a rubric. Agents are versioned (save a draft, publish it), have tools (their own file system, and your HTTP endpoints), and every change is in the org’s audit log. servers: - url: https://guidinghand.ai description: Production - url: https://dev.guidinghand.ai description: Development (Stripe test mode) security: - bearerAuth: [] tags: - name: Agents - name: Agent files - name: Agent tools - name: Sessions - name: Tasks - name: Webhooks - name: Audit log - name: Test cases - name: Test sets - name: Test runs - name: Start states - name: Runners paths: /v1/test_runs: get: tags: - Test runs summary: List test runs description: Newest first. operationId: listTestRuns parameters: - name: status in: query required: false description: Only runs with this status. schema: $ref: '#/components/schemas/TestRunStatus' - name: test_set_id in: query required: false description: Only runs of this test set. schema: type: string - name: q in: query required: false description: >- Search: only runs whose name or `test_run_id` has the text containing this text (case-insensitive, up to 100 characters). schema: type: string maxLength: 100 - name: limit in: query required: false description: How many to return, 1 to 100. schema: type: integer default: 20 minimum: 1 maximum: 100 - name: cursor in: query required: false description: '`next_cursor` from the previous page.' schema: type: string - name: include in: query required: false description: '`total_count` adds how many match across every page.' schema: type: string example: total_count responses: '200': description: OK content: application/json: schema: type: object required: - data - has_more - next_cursor properties: data: type: array items: $ref: '#/components/schemas/TestRun' has_more: type: boolean next_cursor: type: - string - 'null' description: Pass as `cursor` to get the next page. total_count: type: integer description: >- How many match the filters across every page. Only with `include=total_count`. '401': $ref: '#/components/responses/E401' components: schemas: TestRunStatus: type: string enum: - queued - running - completed - cancelled TestRun: type: object description: >- A run of test cases against one or more agents, N tries each. Every try is an attempt. properties: object: const: test_run test_run_id: type: string example: tr_Vb7sT2Lc0aQ3 name: type: string test_set_id: type: - string - 'null' description: The test set it ran, or null for a list of test cases. agents: type: array items: type: string example: - default - lenovo-support status: $ref: '#/components/schemas/TestRunStatus' description: '`completed` once none of its attempts are left.' progress: type: object description: >- The run’s tries: how many are queued, running, passed, failed or ended in an error. properties: total: type: integer queued: type: integer running: type: integer passed: type: integer failed: type: integer error: type: integer pass_rate: type: object additionalProperties: type: - number - 'null' minimum: 0 maximum: 1 description: Per agent, from 0 to 1. Errors don’t count against an agent. example: default: 0.54 lenovo-support: 0.63 metadata: $ref: '#/components/schemas/Metadata' created_at: type: string format: date-time started_at: type: - string - 'null' format: date-time finished_at: type: - string - 'null' format: date-time Metadata: type: object additionalProperties: type: string maxLength: 500 maxProperties: 50 description: >- Your own ids and labels (e.g. a ticket or customer id), returned as given. example: customer_id: cus_42 Error: type: object required: - error properties: error: type: object required: - type - message properties: type: type: string enum: - invalid_request - authentication - payment_required - permission - not_found - conflict - rate_limit - server_error message: type: string code: type: string description: >- Why it was refused, when there’s more to say than the status. Starting a task: `insufficient_balance`, `auto_topup_limit_reached` or `card_needs_attention` (402: the balance can’t cover a minute; add funds, raise the auto top-up limit, or update the card), `concurrency_limit` (429), `model_unavailable` (503: the agent’s `model` can’t run on this server; choose another). On `/respond`: `already_answered` (someone answered or decided first: see `answered_by`) or `not_pending` (that question or approval isn’t open any more). The GuidingHand app hears two more, which the API never returns: `customer_answers_off` and `customer_approvals_off` (the agent keeps its questions or approvals for your team). Deleting a start state that test cases use: `in_use` (409, with `test_case_ids`). answered_by: type: string enum: - customer - operator - timeout description: >- With `already_answered`: who answered or decided first (`customer`: the person at the computer; `timeout`: nobody decided an approval within the agent’s `approval_timeout_minutes`, so it was denied). test_case_ids: type: array items: type: string description: 'With `in_use`: the test cases that use the start state.' responses: E401: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: An org API key (`gh_live_…`) from Settings → API keys in the console. ````