> ## 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 run attempts ## OpenAPI ````yaml /api-reference/openapi.json get /v1/test_runs/{test_run_id}/attempts 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/{test_run_id}/attempts: parameters: - name: test_run_id in: path required: true description: The test run’s id (`tr_…`). schema: type: string get: tags: - Test runs summary: List test run attempts operationId: listTestRunAttempts parameters: - name: test_case_id in: query required: false description: Only this case’s attempts (an id or key). schema: type: string - name: agent_id in: query required: false description: Only this agent’s attempts. schema: type: string - name: outcome in: query required: false description: Only attempts with this outcome. schema: type: string enum: - passed - failed - error - 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 responses: '200': description: OK content: application/json: schema: type: object required: - data - has_more - next_cursor properties: data: type: array items: $ref: '#/components/schemas/Attempt' has_more: type: boolean next_cursor: type: - string - 'null' description: Pass as `cursor` to get the next page. '401': $ref: '#/components/responses/E401' '404': $ref: '#/components/responses/E404' components: schemas: Attempt: type: object description: >- One try of one case with one agent: a fresh machine, a real GuidingHand task on it, the simulated customer, the check and the judge. properties: object: const: attempt attempt_id: type: string example: at_Lc0aQ3Vb7sT2 test_run_id: type: string test_case_id: type: string key: type: - string - 'null' agent_id: type: string try: type: integer description: Which try of this case and agent, from 1. retry_of: type: - string - 'null' description: The attempt this one retries, after an error. status: type: string enum: - queued - preparing - running - checking - done - cancelled outcome: type: - string - 'null' enum: - passed - failed - error - null description: >- `error`: something on GuidingHand’s side (the machine didn’t start, the check didn’t print `False` before the task, …). Errors never count against the agent and are retried up to 2 times. task_id: type: - string - 'null' description: The GuidingHand task it ran. replay_url: type: - string - 'null' description: The task’s replay in the console. check: type: - object - 'null' description: The check script’s output before and after the task. properties: before: type: - string - 'null' after: type: - string - 'null' passed: type: - boolean - 'null' judge: type: - object - 'null' description: The rubric’s verdict. properties: passed: type: boolean reason: type: string explanation: type: - string - 'null' description: >- Why it passed or failed, in a few plain sentences: what the agent did and what the check and the judge found. Null while it runs, and for an error (see `error`). customer: type: array description: The simulated customer’s turns. items: type: object properties: question: type: string answer: type: string actions: type: array items: type: string enum: - admin_yes - admin_no - type_secret - press_enter error: type: - string - 'null' metrics: type: - object - 'null' properties: active_seconds: type: integer steps: type: integer questions: type: integer approvals: type: integer cost_cents: type: integer runner_id: type: - string - 'null' created_at: type: string format: date-time started_at: type: - string - 'null' format: date-time finished_at: type: - string - 'null' format: date-time 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' E404: description: Not found in this org. 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. ````