---
title: "Get multiple runs by IDs"
method: POST
path: "/v1/runs/batch"
tags: ["Runs"]
---

# Get multiple runs by IDs

`POST /v1/runs/batch`

Retrieve multiple runs by their IDs in a single request. Returns found runs and lists any IDs that were not found or not owned. Maximum 100 IDs per request.

## Request body

- object — Batch runs request
  - `run_ids` string[], required — Array of run IDs (1-100)

## Response `200`

Request succeeded. Returns found runs in `data` and any missing IDs in `not_found`.

- object — Batch get runs response
  - `data` object[], required — Found runs
    - `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
  - `not_found` string[], nullable, required — Run IDs that were not found or not owned. Null if all found.

## Other responses

- `400` — Invalid request - empty array, exceeds 100 IDs, or malformed input
- `401` — Unauthorized - Invalid or missing API key
- `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)