---
title: "Get run by ID"
method: GET
path: "/v1/runs/{id}"
tags: ["Runs"]
---

# Get run by ID

`GET /v1/runs/{id}`

Get detailed information about a specific automation run by its ID.

## Path parameters

- `id` string, required — Run ID

## Query parameters

- `screenshots` 'base64' | 'url' | 'none' — Screenshot delivery mode. url: absolute URLs to screenshot images. base64: inline data URIs. none: omit screenshots. Defaults to url.
- `html` 'url' | 'none' — HTML snapshot delivery mode. url: absolute URLs to HTML snapshot pages (only non-null when capture_config.html was enabled). none: omit HTML URLs. Defaults to url.

## Response `200`

Run details

- object — A single automation run
  - `run_id` string, required — Unique identifier for the run
  - `status` 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED', required — Current status of the run
  - `goal` string, required — Natural language goal for this automation run
  - `created_at` string, required — ISO 8601 timestamp when run was created
  - `started_at` string, nullable, required — ISO 8601 timestamp when run started executing
  - `finished_at` string, nullable, required — ISO 8601 timestamp when run finished
  - `num_of_steps` integer, nullable, required — Number of steps taken during the automation run. Null while the run is still in progress.
  - `result` object, nullable, required — Extracted data from the automation run
  - `output_schema` object, nullable, required — Provider-supported structured-output schema subset originally requested for this run. Null when no output_schema was provided.
  - `profile_attached` boolean, required — Whether this run attached a Browser Context Profile internally.
  - `profile_id` string, nullable, required — Browser Context Profile ID attached to this run, or null when no profile attached.
  - `error` object, nullable, required — Error details. Null if the run succeeded or is still running.
    - `code` string — Machine-readable error code for programmatic handling
    - `message` string, required — Error message describing why the run failed
    - `category` 'SYSTEM_FAILURE' | 'AGENT_FAILURE' | 'BILLING_FAILURE' | 'UNKNOWN', required — Error category. SYSTEM_FAILURE = TinyFish issue (retry). AGENT_FAILURE = run issue (fix input). BILLING_FAILURE = out of credits (add credits). UNKNOWN = unclassified (treat as retryable).
    - `retry_after` number, nullable — Suggested retry delay in seconds (null if not retryable)
    - `help_url` string — URL to documentation for troubleshooting
    - `help_message` string — Human-readable help message with guidance
    - `profile_hint` object — Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile.
      - `message` string, required — Human-readable profile setup nudge for auth walls and bot challenges.
      - `setup_url` string, required — Internal URL to set up the caller’s default Browser Context Profile.
      - `reason` 'auth_wall' | 'bot_challenge', required — Why a Browser Context Profile may solve this failed run.
  - `profile_hint` object — Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile.
    - `message` string, required — Human-readable profile setup nudge for auth walls and bot challenges.
    - `setup_url` string, required — Internal URL to set up the caller’s default Browser Context Profile.
    - `reason` 'auth_wall' | 'bot_challenge', required — Why a Browser Context Profile may solve this failed run.
  - `streaming_url` string, nullable, required — URL to watch live browser session (available while running)
  - `browser_config` object, nullable, required — Browser configuration used for the run
    - `proxy_enabled` boolean, nullable, required — Whether proxy was enabled
    - `proxy_country_code` string, nullable, required — Country code for proxy
  - `video_url` string, nullable, required — Presigned URL to the video recording of this run. Null if no recording is available. URL expires after 15 minutes.
  - `steps` object[], required — Steps the agent took during this run.
    - `id` string, required — Unique identifier for this step
    - `timestamp` string, required — ISO 8601 timestamp when this step occurred
    - `status` 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED', required — Current status of the run
    - `action` string, nullable, required — Description of the action taken in this step
    - `screenshot` string, nullable, required — Screenshot for this step. Format depends on the screenshots query param: base64 returns a data URI (data:image/jpeg;base64,...), url returns an absolute URL to the screenshot. Null if screenshots=none or no screenshot available.
    - `html` string, nullable, required — URL to the full-page HTML snapshot captured at this step. Null if html=none or no HTML was captured. Requires capture_config.html: true when starting the run.
    - `duration` string, nullable, required — Time taken for this step

## Other responses

- `401` — Unauthorized - Invalid or missing API key
- `404` — Run not found
- `500` — Internal server error

---

[API](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api.md) · [All operations](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tinyfish/tinyfish-web-agent-automation-api/revisions/bea716bc627d/schema)