---
title: "List and search runs"
method: GET
path: "/v1/runs"
tags: ["Runs"]
---

# List and search runs

`GET /v1/runs`

List automation runs with optional filtering by status, goal text, and date range. Returns paginated results with total count. Default sort order is newest first.

## Query parameters

- `status` 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' — Filter by run status
- `goal` string — Filter runs by goal text (case-insensitive partial match)
- `created_after` string, date-time — Filter runs created after this ISO 8601 timestamp
- `created_before` string, date-time — Filter runs created before this ISO 8601 timestamp
- `sort_direction` 'asc' | 'desc' — Sort order by created_at
- `cursor` string — Cursor for pagination (from previous response)
- `limit` integer — Maximum number of results to return (1-100)

## Response `200`

Paginated list of runs

- object — Paginated list of runs
  - `data` object[], required — Array of 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
  - `pagination` object, required — Pagination information
    - `total` integer, required — Total number of runs matching the current filters
    - `next_cursor` string, nullable, required — Cursor for fetching next page. Null if no more results.
    - `has_more` boolean, required — Whether there are more results after this page

## Other responses

- `400` — Invalid request parameters
- `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)