> ## 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 start states > Runners’ images first, then your org’s start states, newest first. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/start_states 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/start_states: get: tags: - Start states summary: List start states description: Runners’ images first, then your org’s start states, newest first. operationId: listStartStates parameters: - 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/StartState' has_more: type: boolean next_cursor: type: - string - 'null' description: Pass as `cursor` to get the next page. '401': $ref: '#/components/responses/E401' components: schemas: StartState: type: object description: >- A machine to start each try from: a runner’s base OS install (`kind: image`, read-only, every org sees it) or a saved machine made from one (`kind: state`). properties: object: const: start_state start_state_id: type: string example: ss_0aQ3Vb7sT2Lc kind: type: string enum: - image - state name: type: string example: Printer offline description: type: string from: type: - string - 'null' example: win10-22h2 description: The image or start state it was made from (null for an image). method: type: - string - 'null' enum: - hand - script - instruction - null description: >- How it was set up: by hand on its open machine, by a script, or by a GuidingHand task. script: type: - string - 'null' instruction: type: - string - 'null' agent_id: type: - string - 'null' description: The agent that ran the `instruction`. task_id: type: - string - 'null' description: 'With `method: instruction`: the task that set it up.' status: $ref: '#/components/schemas/StartStateStatus' description: >- `building`: its script or instruction is running. `open`: its machine is running for someone to set up or look at. `saving`, then `ready`. `failed`: see `error`. version: type: integer description: >- Goes up by one with each save; 0 until first saved. A test run uses the version current when it was created. os: type: string example: windows labels: type: array items: type: string description: 'Where it can run: its runner’s labels.' example: - vm runner_id: type: - string - 'null' description: >- The runner that holds its disk (null for an image: any runner that has it). error: type: - string - 'null' view: type: - object - 'null' description: While its machine is open. properties: screen_url: type: string input_url: type: string expires_at: type: string format: date-time description: It closes itself after 2 hours without input. metadata: $ref: '#/components/schemas/Metadata' created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time StartStateStatus: type: string enum: - building - open - saving - ready - failed 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. ````