v1

latestOpenAPI 3.0.02026-07-26300209.6 KB

Runs

Get run by ID

Get detailed information about a specific automation run by its ID.

get/v1/runs/{id}

Path parameters

idstring required

Run ID

Example:a1b2c3d4-e5f6-7890-abcd-ef1234567890

Run ID

Query parameters

screenshots'base64' | 'url' | 'none'

Screenshot delivery mode. url: absolute URLs to screenshot images. base64: inline data URIs. none: omit screenshots. Defaults to url.

Example:url

Screenshot delivery mode. url: absolute URLs to screenshot images. base64: inline data URIs. none: omit screenshots. Defaults to url.

html'url' | 'none'

HTML snapshot delivery mode. url: absolute URLs to HTML snapshot pages (only non-null when capture_config.html was enabled). none: omit HTML URLs. Defaults to url.

Example:url

HTML snapshot delivery mode. url: absolute URLs to HTML snapshot pages (only non-null when capture_config.html was enabled). none: omit HTML URLs. Defaults to url.

Response

Run details

run_idstring required

Unique identifier for the run

status'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' required

Current status of the run

goalstring required

Natural language goal for this automation run

created_atstring required

ISO 8601 timestamp when run was created

started_atstring nullable required

ISO 8601 timestamp when run started executing

finished_atstring nullable required

ISO 8601 timestamp when run finished

num_of_stepsinteger nullable required

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

resultobject nullable required

Extracted data from the automation run

output_schemaobject nullable required

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

profile_attachedboolean required

Whether this run attached a Browser Context Profile internally.

profile_idstring nullable required

Browser Context Profile ID attached to this run, or null when no profile attached.

streaming_urlstring nullable required

URL to watch live browser session (available while running)

video_urlstring nullable required

Presigned URL to the video recording of this run. Null if no recording is available. URL expires after 15 minutes.

Example response

{
  "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,
  "output_schema": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string"
      },
      "price": {
        "type": "number"
      }
    },
    "required": [
      "title",
      "price"
    ]
  },
  "profile_attached": true,
  "profile_id": "prof_abc123",
  "error": {
    "code": "service_busy",
    "message": "Browser crashed during execution",
    "category": "SYSTEM_FAILURE",
    "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.",
    "profile_hint": {
      "setup_url": "/profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge",
      "reason": "auth_wall"
    }
  },
  "profile_hint": {
    "setup_url": "/profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge",
    "reason": "auth_wall"
  },
  "streaming_url": "https://stream.agent.tinyfish.ai/session/xyz",
  "browser_config": {
    "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": "https://agent.tinyfish.ai/runs/a1b2c3d4/steps/evt_abc123/screenshot",
      "html": "https://agent.tinyfish.ai/runs/a1b2c3d4/steps/evt_abc123/html",
      "duration": "1.2s"
    }
  ]
}