> ## 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. # Get an attempt > The attempt, with the copy of the test case it ran (`test_case`). ## OpenAPI ````yaml /api-reference/openapi.json get /v1/attempts/{attempt_id} 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/attempts/{attempt_id}: parameters: - name: attempt_id in: path required: true description: The attempt’s id (`at_…`). schema: type: string get: tags: - Test runs summary: Get an attempt description: The attempt, with the copy of the test case it ran (`test_case`). operationId: getAttempt responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/Attempt' - type: object properties: test_case: $ref: '#/components/schemas/TestCase' description: The case as it was when the run started. '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 TestCase: type: object description: A problem on a machine, and how to tell it’s fixed. properties: object: const: test_case test_case_id: type: string example: tc_8Kq2mZ0aLp4x key: type: - string - 'null' pattern: ^(?!tc_)[A-Za-z0-9._-]{1,64}$ example: DSP-01 description: >- Your own id for the case, unique in the org: 1 to 64 of `A-Za-z0-9._-`, not starting with `tc_`. Every `{test_case_id}` in the API also takes it. name: type: string minLength: 1 maxLength: 200 example: Apps switched to dark mode prompt: type: string minLength: 1 maxLength: 8000 example: All my windows suddenly went black. How do I get the white back? description: 'What the customer says to the agent: the task’s prompt.' start_state: type: string example: win10-22h2 description: >- The start state (`ss_…`) or image (e.g. `win10-22h2`) each try’s machine is made from. setup_script: type: - string - 'null' maxLength: 100000 description: >- Runs at the start of every try, elevated, as the signed-in user: it breaks the machine the way the case needs. success: type: object properties: check_script: type: - string - 'null' maxLength: 100000 description: >- Runs on the machine (elevated, as the signed-in user) and prints `True` once the problem is fixed. It must print `False` before the task, or the attempt is an `error`. The agent’s final answer is in the `GH_AGENT_ANSWER` environment variable, and `GH_CHECK_PHASE` is `before` or `after` the task. rubric: type: - string - 'null' maxLength: 8000 description: >- What a fix looks like, in plain language. A model judges it from the recorded conversation and the first and last screens. description: >- How to tell the problem is fixed. An attempt passes only when each one it has passes. customer: oneOf: - $ref: '#/components/schemas/Customer' - type: 'null' description: >- The simulated customer. Null: the test set’s `customer`, else a built-in default. operator: type: object properties: approvals: type: string enum: - approve - deny description: How the agent’s approval requests are decided during the test. limits: type: object properties: minutes: type: integer minimum: 1 maximum: 60 default: 10 description: The task is stopped after this many minutes (1 to 60). steps: type: - integer - 'null' minimum: 1 maximum: 500 description: >- Model turns (1 to 500). Null: the agent’s own `guardrails.max_steps`. runs_on: type: string example: vm description: >- A runner label the case needs: `vm` for any virtual machine, or one of your runners’ labels (e.g. `lenovo`). category: type: - string - 'null' example: Display & graphics tags: type: array items: type: string maxLength: 64 maxItems: 50 example: - uac metadata: $ref: '#/components/schemas/Metadata' created_at: type: string format: date-time updated_at: type: string format: date-time Customer: type: object description: >- The simulated customer who answers the agent during a test: a model with this persona, these facts and the machine’s screen. It never sees the expected fix or the check. properties: persona: type: string example: Retired teacher. Not technical. Short, polite answers. description: Who they are and how they answer. facts: type: object maxProperties: 50 additionalProperties: oneOf: - type: string - type: object required: - secret properties: secret: type: string description: >- A secret: the simulated customer’s model only sees its name, and can type it into the focused field. description: >- What the customer knows, by name (up to 50). A `{ "secret": … }` value is never shown to the model: the customer can only type it into the field that has focus. example: Wi-Fi network: HomeNet Wi-Fi password: secret: blue-kite-42 clicks_admin_prompts: type: boolean description: >- When the agent asks, the customer clicks Yes on an admin (UAC) prompt. does_steps: type: boolean description: >- The customer does steps themselves when the agent asks. When false, they ask the agent to do it. 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' 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. ````