Skip to main content
GET
/
v1
/
runs
/
{id}
Get run by ID
curl --request GET \
  --url https://agent.tinyfish.ai/v1/runs/{id} \
  --header 'X-API-Key: <api-key>'
{
  "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "goal": "Find all pricing information",
  "created_at": "2026-01-14T10:30:00Z",
  "started_at": "2026-01-14T10:30:05Z",
  "finished_at": "2026-01-14T10:31:30Z",
  "num_of_steps": 5,
  "result": {},
  "output_schema": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string"
      },
      "price": {
        "type": "number"
      }
    },
    "required": [
      "title",
      "price"
    ]
  },
  "error": {
    "message": "Browser crashed during execution",
    "category": "SYSTEM_FAILURE",
    "code": "service_busy",
    "retry_after": 60,
    "help_url": "https://docs.tinyfish.ai/prompting-guide",
    "help_message": "Need help? Check out our goal prompting guide for tips and examples."
  },
  "streaming_url": "https://stream.agent.tinyfish.ai/session/xyz",
  "browser_config": {
    "proxy_enabled": false,
    "proxy_country_code": "US"
  },
  "video_url": "https://s3.amazonaws.com/bucket/eva-traces/run-id/video/recording.webm?...",
  "steps": [
    {
      "id": "evt_abc123",
      "timestamp": "2026-01-14T10:30:05Z",
      "status": "COMPLETED",
      "action": "Click the login button",
      "screenshot": "data:image/jpeg;base64,/9j/4AAQSkZJRgAB...",
      "duration": "1.2s"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
X-API-Key
string
header
required

API key for authentication. Get your key from the API Keys page.

Path Parameters

​
id
string
required

Run ID

Pattern: ^[A-Za-z0-9_-]+$
Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Query Parameters

​
screenshots
enum<string>
default:none

Whether to include base64-encoded screenshots in steps. Defaults to none.

Available options:
base64,
none
Example:

"base64"

Response

Run details

A single automation run

​
run_id
string
required

Unique identifier for the run

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
status
enum<string>
required

Current status of the run

Available options:
PENDING,
RUNNING,
COMPLETED,
FAILED,
CANCELLED
Example:

"COMPLETED"

​
goal
string
required

Natural language goal for this automation run

Example:

"Find all pricing information"

​
created_at
string
required

ISO 8601 timestamp when run was created

Example:

"2026-01-14T10:30:00Z"

​
started_at
string | null
required

ISO 8601 timestamp when run started executing

Example:

"2026-01-14T10:30:05Z"

​
finished_at
string | null
required

ISO 8601 timestamp when run finished

Example:

"2026-01-14T10:31:30Z"

​
num_of_steps
integer | null
required

Number of steps taken during the automation run. Null while the run is still in progress.

Required range: x >= 0
Example:

5

​
result
object
required

Extracted data from the automation run

​
output_schema
object
required

Provider-supported structured-output schema subset originally requested for this run. Null when no output_schema was provided.

Example:
{
  "type": "object",
  "properties": {
    "title": { "type": "string" },
    "price": { "type": "number" }
  },
  "required": ["title", "price"]
}
​
error
object
required

Error details. Null if the run succeeded or is still running.

​
streaming_url
string | null
required

URL to watch live browser session (available while running)

Example:

"https://stream.agent.tinyfish.ai/session/xyz"

​
browser_config
object
required

Browser configuration used for the run

​
video_url
string | null
required

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
object[]
required

Steps the agent took during this run.