TinyFish Runs API
Endpoints for retrieving automation run data
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/tinyfish-runs-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: TinyFish Browser Automation Runs API
version: 1.0.0
description: Create remote browser sessions for direct Playwright/CDP control.
contact:
name: TinyFish Support
email: support@tinyfish.ai
servers:
- url: https://api.browser.tinyfish.ai
tags:
- name: Runs
description: Endpoints for retrieving automation run data
paths:
/v1/runs:
get:
operationId: listRuns
description: 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.
summary: List and search runs
tags:
- Runs
security:
- ApiKeyAuth: []
parameters:
- schema:
type: string
enum:
- PENDING
- RUNNING
- COMPLETED
- FAILED
- CANCELLED
description: Filter by run status
example: COMPLETED
required: false
description: Filter by run status
name: status
in: query
- schema:
type: string
maxLength: 500
description: Filter runs by goal text (case-insensitive partial match)
example: linkedin
required: false
description: Filter runs by goal text (case-insensitive partial match)
name: goal
in: query
- schema:
type: string
format: date-time
description: Filter runs created after this ISO 8601 timestamp
example: '2026-01-01T00:00:00Z'
required: false
description: Filter runs created after this ISO 8601 timestamp
name: created_after
in: query
- schema:
type: string
format: date-time
description: Filter runs created before this ISO 8601 timestamp
example: '2026-02-01T00:00:00Z'
required: false
description: Filter runs created before this ISO 8601 timestamp
name: created_before
in: query
- schema:
type: string
enum:
- asc
- desc
default: desc
description: Sort order by created_at
example: desc
required: false
description: Sort order by created_at
name: sort_direction
in: query
- schema:
type: string
description: Cursor for pagination (from previous response)
example: eyJpZCI6ImFiYyIsImNyZWF0ZWRBdCI6IjIwMjYtMDEtMDFUMTI6MDA6MDBaIn0=
required: false
description: Cursor for pagination (from previous response)
name: cursor
in: query
- schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: Maximum number of results to return (1-100)
example: 20
required: false
description: Maximum number of results to return (1-100)
name: limit
in: query
responses:
'200':
description: Paginated list of runs
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
run_id:
type: string
description: Unique identifier for the run
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
status:
type: string
enum:
- PENDING
- RUNNING
- COMPLETED
- FAILED
- CANCELLED
description: Current status of the run
example: COMPLETED
goal:
type: string
description: Natural language goal for this automation run
example: Find all pricing information
created_at:
type: string
description: ISO 8601 timestamp when run was created
example: '2026-01-14T10:30:00Z'
started_at:
type:
- string
- 'null'
description: ISO 8601 timestamp when run started executing
example: '2026-01-14T10:30:05Z'
finished_at:
type:
- string
- 'null'
description: ISO 8601 timestamp when run finished
example: '2026-01-14T10:31:30Z'
num_of_steps:
type:
- integer
- 'null'
minimum: 0
description: Number of steps taken during the automation run. Null while the run is still in progress.
example: 5
result:
type:
- object
- 'null'
additionalProperties: {}
description: Extracted data from the automation run
schema_validation:
type:
- object
- 'null'
properties:
valid:
type: boolean
description: Whether the run result matched the provided output_schema.
example: false
re_prompt_attempts:
type: integer
minimum: 0
maximum: 2
description: Number of schema-repair re-prompt attempts performed for the run result.
example: 1
errors:
type: array
items:
type: object
properties:
path:
type: string
description: Path to the field that failed schema validation.
example: price
expected:
type: string
description: Expected schema type or constraint.
example: number
received:
type: string
description: Actual value type encountered in the run result.
example: string
message:
type: string
description: Human-readable validation error message.
example: Expected number, received string
required:
- path
- expected
- received
- message
description: Validation mismatches captured for the final run result.
required:
- valid
- re_prompt_attempts
- errors
description: Schema validation result. Null when no output_schema was provided for the run.
example:
valid: false
re_prompt_attempts: 1
errors:
- path: price
expected: number
received: string
message: Expected number, received string
error:
type:
- object
- 'null'
properties:
code:
type: string
description: Machine-readable error code for programmatic handling
example: service_busy
message:
type: string
description: Error message describing why the run failed
example: Browser crashed during execution
category:
type: string
enum:
- SYSTEM_FAILURE
- AGENT_FAILURE
- BILLING_FAILURE
- UNKNOWN
description: 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).
example: SYSTEM_FAILURE
retry_after:
type:
- number
- 'null'
description: Suggested retry delay in seconds (null if not retryable)
example: 60
help_url:
type: string
description: URL to documentation for troubleshooting
example: https://docs.tinyfish.ai/prompting-guide
help_message:
type: string
description: Human-readable help message with guidance
example: Need help? Check out our goal prompting guide for tips and examples.
required:
- message
- category
description: Error details. Null if the run succeeded or is still running.
streaming_url:
type:
- string
- 'null'
description: URL to watch live browser session (available while running)
example: https://stream.agent.tinyfish.ai/session/xyz
browser_config:
type:
- object
- 'null'
properties:
proxy_enabled:
type:
- boolean
- 'null'
description: Whether proxy was enabled
example: false
proxy_country_code:
type:
- string
- 'null'
description: Country code for proxy
example: US
required:
- proxy_enabled
- proxy_country_code
description: Browser configuration used for the run
required:
- run_id
- status
- goal
- created_at
- started_at
- finished_at
- num_of_steps
- result
- schema_validation
- error
- streaming_url
- browser_config
description: A run summary (without video_url and steps)
description: Array of runs
pagination:
type: object
properties:
total:
type: integer
description: Total number of runs matching the current filters
example: 142
next_cursor:
type:
- string
- 'null'
description: Cursor for fetching next page. Null if no more results.
example: eyJpZCI6ImFiYyIsImNyZWF0ZWRBdCI6IjIwMjYtMDEtMDFUMTI6MDA6MDBaIn0=
has_more:
type: boolean
description: Whether there are more results after this page
example: true
required:
- total
- next_cursor
- has_more
description: Pagination information
required:
- data
- pagination
description: Paginated list of runs
'400':
description: Invalid request parameters
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- MISSING_API_KEY
- INVALID_API_KEY
- INVALID_INPUT
- RATE_LIMIT_EXCEEDED
- INTERNAL_ERROR
- UNAUTHORIZED
- FORBIDDEN
- NOT_FOUND
- SERVICE_BUSY
- TIMEOUT
- INSUFFICIENT_CREDITS
- CONTENT_POLICY_VIOLATION
- MAX_STEPS_EXCEEDED
- SITE_BLOCKED
- TASK_FAILED
- CANCELLED
description: Machine-readable error code
example: INVALID_INPUT
message:
type: string
description: Human-readable error message
example: Field "url" is required and must be a string
details:
description: Additional error details (validation errors, etc.)
required:
- code
- message
required:
- error
description: Standard error response format
'401':
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- MISSING_API_KEY
- INVALID_API_KEY
- INVALID_INPUT
- RATE_LIMIT_EXCEEDED
- INTERNAL_ERROR
- UNAUTHORIZED
- FORBIDDEN
- NOT_FOUND
- SERVICE_BUSY
- TIMEOUT
- INSUFFICIENT_CREDITS
- CONTENT_POLICY_VIOLATION
- MAX_STEPS_EXCEEDED
- SITE_BLOCKED
- TASK_FAILED
- CANCELLED
description: Machine-readable error code
example: INVALID_INPUT
message:
type: string
description: Human-readable error message
example: Field "url" is required and must be a string
details:
description: Additional error details (validation errors, etc.)
required:
- code
- message
required:
- error
description: Standard error response format
'500':
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- MISSING_API_KEY
- INVALID_API_KEY
- INVALID_INPUT
- RATE_LIMIT_EXCEEDED
- INTERNAL_ERROR
- UNAUTHORIZED
- FORBIDDEN
- NOT_FOUND
- SERVICE_BUSY
- TIMEOUT
- INSUFFICIENT_CREDITS
- CONTENT_POLICY_VIOLATION
- MAX_STEPS_EXCEEDED
- SITE_BLOCKED
- TASK_FAILED
- CANCELLED
description: Machine-readable error code
example: INVALID_INPUT
message:
type: string
description: Human-readable error message
example: Field "url" is required and must be a string
details:
description: Additional error details (validation errors, etc.)
required:
- code
- message
required:
- error
description: Standard error response format
/v1/runs/batch:
post:
operationId: batchGetRuns
summary: Get multiple runs by IDs
description: 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.
tags:
- Runs
security:
- ApiKeyAuth: []
requestBody:
description: Array of run IDs to fetch
content:
application/json:
schema:
type: object
properties:
run_ids:
type: array
items:
type: string
minItems: 1
maxItems: 100
description: Array of run IDs (1-100)
example:
- a1b2c3d4-e5f6-7890-abcd-ef1234567890
- b2c3d4e5-f6a7-8901-bcde-f23456789012
required:
- run_ids
description: Batch runs request
responses:
'200':
description: Request succeeded. Returns found runs in `data` and any missing IDs in `not_found`.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
run_id:
type: string
description: Unique identifier for the run
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
status:
type: string
enum:
- PENDING
- RUNNING
- COMPLETED
- FAILED
- CANCELLED
description: Current status of the run
example: COMPLETED
goal:
type: string
description: Natural language goal for this automation run
example: Find all pricing information
created_at:
type: string
description: ISO 8601 timestamp when run was created
example: '2026-01-14T10:30:00Z'
started_at:
type:
- string
- 'null'
description: ISO 8601 timestamp when run started executing
example: '2026-01-14T10:30:05Z'
finished_at:
type:
- string
- 'null'
description: ISO 8601 timestamp when run finished
example: '2026-01-14T10:31:30Z'
num_of_steps:
type:
- integer
- 'null'
minimum: 0
description: Number of steps taken during the automation run. Null while the run is still in progress.
example: 5
result:
type:
- object
- 'null'
additionalProperties: {}
description: Extracted data from the automation run
schema_validation:
type:
- object
- 'null'
properties:
valid:
type: boolean
description: Whether the run result matched the provided output_schema.
example: false
re_prompt_attempts:
type: integer
minimum: 0
maximum: 2
description: Number of schema-repair re-prompt attempts performed for the run result.
example: 1
errors:
type: array
items:
type: object
properties:
path:
type: string
description: Path to the field that failed schema validation.
example: price
expected:
type: string
description: Expected schema type or constraint.
example: number
received:
type: string
description: Actual value type encountered in the run result.
example: string
message:
type: string
description: Human-readable validation error message.
example: Expected number, received string
required:
- path
- expected
- received
- message
description: Validation mismatches captured for the final run result.
required:
- valid
- re_prompt_attempts
- errors
description: Schema validation result. Null when no output_schema was provided for the run.
example:
valid: false
re_prompt_attempts: 1
errors:
- path: price
expected: number
received: string
message: Expected number, received string
error:
type:
- object
- 'null'
properties:
code:
type: string
description: Machine-readable error code for programmatic handling
example: service_busy
message:
type: string
description: Error message describing why the run failed
example: Browser crashed during execution
category:
type: string
enum:
- SYSTEM_FAILURE
- AGENT_FAILURE
- BILLING_FAILURE
- UNKNOWN
description: 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).
example: SYSTEM_FAILURE
retry_after:
type:
- number
- 'null'
description: Suggested retry delay in seconds (null if not retryable)
example: 60
help_url:
type: string
description: URL to documentation for troubleshooting
example: https://docs.tinyfish.ai/prompting-guide
help_message:
type: string
description: Human-readable help message with guidance
example: Need help? Check out our goal prompting guide for tips and examples.
required:
- message
- category
description: Error details. Null if the run succeeded or is still running.
streaming_url:
type:
- string
- 'null'
description: URL to watch live browser session (available while running)
example: https://stream.agent.tinyfish.ai/session/xyz
browser_config:
type:
- object
- 'null'
properties:
proxy_enabled:
type:
- boolean
- 'null'
description: Whether proxy was enabled
example: false
proxy_country_code:
type:
- string
- 'null'
description: Country code for proxy
example: US
required:
- proxy_enabled
- proxy_country_code
description: Browser configuration used for the run
video_url:
type:
- string
- 'null'
description: Presigned URL to the video recording of this run. Null if no recording is available. URL expires after 15 minutes.
example: https://s3.amazonaws.com/bucket/eva-traces/run-id/video/recording.webm?...
steps:
type: array
items:
type: object
properties:
id:
type: string
description: Unique identifier for this step
example: evt_abc123
timestamp:
type: string
description: ISO 8601 timestamp when this step occurred
example: '2026-01-14T10:30:05Z'
status:
type: string
enum:
- PENDING
- RUNNING
- COMPLETED
- FAILED
- CANCELLED
description: Current status of the run
example: COMPLETED
action:
type:
- string
- 'null'
description: Description of the action taken in this step
example: Click the login button
screenshot:
type:
- string
- 'null'
description: Base64-encoded JPEG screenshot at this step (data:image/jpeg;base64,...). Null if screenshots=none or no screenshot available.
example: data:image/jpeg;base64,/9j/4AAQSkZJRgAB...
duration:
type:
- string
- 'null'
description: Time taken for this step
example: 1.2s
required:
- id
- timestamp
- status
- action
- screenshot
- duration
description: A single automation step
description: Steps the agent took during this run.
required:
- run_id
- status
- goal
- created_at
- started_at
- finished_at
- num_of_steps
- result
- schema_validation
- error
- streaming_url
- browser_config
- video_url
- steps
description: A single automation run
description: Found runs
not_found:
type:
- array
- 'null'
items:
type: string
description: Run IDs that were not found or not owned. Null if all found.
required:
- data
- not_found
description: Batch get runs response
example:
data:
- run_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
status: COMPLETED
goal: Find all pricing information
created_at: '2024-01-01T00:00:00Z'
started_at: '2024-01-01T00:00:05Z'
# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tinyfish/refs/heads/main/openapi/tinyfish-runs-api-openapi.yml