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

# List and search runs

`GET /v1/runs`

## Request

- Base URL: `https://agent.tinyfish.ai`
- URL: `https://agent.tinyfish.ai/v1/runs`
- Auth: API key in header `X-API-Key`

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-2.md) · [All operations](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2/revisions/c48ef855099d?raw)