Sign in

v60

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-0283227863.6 KB
Agents

File Download Task

Download a file from a website by navigating and clicking download buttons

post/v1/run/tasks/download_files

Headers

x-api-keystring nullable

Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.

Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.

x-user-agentstring nullable

Request body

urlstring nullable

Website URL

webhook_urlstring nullable

Webhook URL to send status updates

proxy_location'RESIDENTIAL' | 'US-CA' | 'US-NY' | 'US-TX' | 'US-FL' | 'US-WA' | 'RESIDENTIAL_ES' | 'RESIDENTIAL_IE' | 'RESIDENTIAL_GB' | 'RESIDENTIAL_IN' | 'RESIDENTIAL_JP' | 'RESIDENTIAL_FR' | 'RESIDENTIAL_DE' | 'RESIDENTIAL_NZ' | 'RESIDENTIAL_ZA' | 'RESIDENTIAL_AR' | 'RESIDENTIAL_AU' | 'RESIDENTIAL_BR' | 'RESIDENTIAL_TR' | 'RESIDENTIAL_CA' | 'RESIDENTIAL_MX' | 'RESIDENTIAL_IT' | 'RESIDENTIAL_NL' | 'RESIDENTIAL_PH' | 'RESIDENTIAL_KR' | 'RESIDENTIAL_SA' | 'RESIDENTIAL_ISP' | 'NONE'
totp_identifierstring nullable

Identifier for TOTP (Time-based One-Time Password) if required

totp_urlstring nullable

TOTP URL to fetch one-time passwords

browser_session_idstring nullable

ID of the browser session to use, which is prefixed by pbs_ e.g. pbs_123456

browser_profile_idstring nullable

ID of a browser profile to reuse for this run

browser_addressstring nullable

The CDP address for the task.

extra_http_headersobject nullable

Additional HTTP headers to include in requests

cdp_connect_headersobject nullable

HTTP headers attached ONLY to the CDP WebSocket handshake when connecting to a remote browser via browser_address. Never forwarded to target websites.

max_screenshot_scrolling_timesinteger nullable

Maximum number of times to scroll for screenshots

navigation_goalstring required

Instructions for navigating to and downloading the file

download_suffixstring nullable

Suffix or complete filename for the downloaded file

download_timeoutnumber nullable

Timeout in seconds for the download operation

max_steps_per_runinteger nullable

Maximum number of steps to execute

Example request

{
  "browser_session_id": "pbs_123456",
  "browser_address": "http://127.0.0.1:9222"
}

Response

Successful Response

run_idstring required

Unique identifier for this run. Run ID starts with tsk_ for task runs and wr_ for workflow runs.

status'created' | 'queued' | 'running' | 'paused' | 'timed_out' | 'failed' | 'terminated' | 'completed' | 'canceled' required
recording_urlstring nullable

URL to the recording of the run

recording_archivedboolean

True when the recording exists but has been archived to cold storage and is not currently accessible.

screenshot_urlsstring[] nullable

List of last n screenshot URLs in reverse chronological order - the first one the list is the latest screenshot.

failure_reasonstring nullable

Reason for failure if the run failed or terminated

created_atstring date-time required

Timestamp when this run was created

modified_atstring date-time required

Timestamp when this run was last modified

queued_atstring date-time nullable

Timestamp when this run was queued

started_atstring date-time nullable

Timestamp when this run started execution

finished_atstring date-time nullable

Timestamp when this run finished

app_urlstring nullable

URL to the application UI where the run can be viewed

browser_session_idstring nullable

ID of the Skyvern persistent browser session used for this run

browser_profile_idstring nullable

ID of the browser profile used for this run

max_screenshot_scrollsinteger nullable

The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot

errorsobject[] nullable

The errors for the run

step_countinteger nullable

Total number of steps executed in this run

run_type'workflow_run' required

Type of run - always workflow_run for workflow runs

run_withstring

Whether the workflow run was executed with agent or code

ai_fallbackboolean nullable

Whether to fallback to AI if code run fails.

script_idstring nullable

ID of the cached script used for this workflow run, if any.

Example response

{
  "run_id": "tsk_123",
  "created_at": "2025-01-01T00:00:00Z",
  "modified_at": "2025-01-01T00:05:00Z",
  "app_url": "https://app.skyvern.com/tasks/tsk_123",
  "browser_session_id": "pbs_123",
  "browser_profile_id": "bp_123",
  "run_with": "agent",
  "run_request": {
    "workflow_id": "wpid_123",
    "proxy_location": {
      "country": "US",
      "subdivision": "CA",
      "city": "New York"
    },
    "totp_url": "https://my-totp-service.com/totp",
    "totp_identifier": "john.doe@example.com",
    "browser_address": "http://127.0.0.1:9222",
    "run_with": "agent"
  }
}