Run an agent

curl --request POST \
  --url https://api.skyvern.com/v1/run/agents \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": "<string>",
  "parameters": {},
  "title": "<string>",
  "proxy_location": "RESIDENTIAL",
  "webhook_url": "<string>",
  "totp_url": "https://my-totp-service.com/totp",
  "totp_identifier": "john.doe@example.com",
  "browser_session_id": "<string>",
  "browser_profile_id": "<string>",
  "max_screenshot_scrolls": 123,
  "max_elapsed_time_minutes": 120,
  "extra_http_headers": {},
  "cdp_connect_headers": {},
  "browser_address": "http://127.0.0.1:9222",
  "ai_fallback": true,
  "run_with": "agent",
  "run_metadata": {}
}
'

{
  "run_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "modified_at": "2023-11-07T05:31:56Z",
  "run_type": "<string>",
  "output": {},
  "downloaded_files": [
    {
      "url": "<string>",
      "checksum": "<string>",
      "filename": "<string>",
      "file_size": 123,
      "modified_at": "2023-11-07T05:31:56Z",
      "artifact_id": "<string>"
    }
  ],
  "recording_url": "<string>",
  "recording_archived": false,
  "screenshot_urls": [
    "<string>"
  ],
  "failure_reason": "<string>",
  "queued_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "finished_at": "2023-11-07T05:31:56Z",
  "app_url": "https://app.skyvern.com/tasks/tsk_123",
  "browser_session_id": "pbs_123",
  "browser_profile_id": "bp_123",
  "max_screenshot_scrolls": 123,
  "script_run": {
    "ai_fallback_triggered": false,
    "script_id": "<string>",
    "script_revision_id": "<string>"
  },
  "errors": [
    {}
  ],
  "step_count": 123,
  "run_with": "agent",
  "ai_fallback": true,
  "script_id": "<string>",
  "run_request": {
    "workflow_id": "<string>",
    "parameters": {},
    "title": "<string>",
    "proxy_location": "RESIDENTIAL",
    "webhook_url": "<string>",
    "totp_url": "https://my-totp-service.com/totp",
    "totp_identifier": "john.doe@example.com",
    "browser_session_id": "<string>",
    "browser_profile_id": "<string>",
    "max_screenshot_scrolls": 123,
    "max_elapsed_time_minutes": 120,
    "extra_http_headers": {},
    "cdp_connect_headers": {},
    "browser_address": "http://127.0.0.1:9222",
    "ai_fallback": true,
    "run_with": "agent",
    "run_metadata": {}
  }
}

POST

run

agents

Run an agent

curl --request POST \
  --url https://api.skyvern.com/v1/run/agents \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": "<string>",
  "parameters": {},
  "title": "<string>",
  "proxy_location": "RESIDENTIAL",
  "webhook_url": "<string>",
  "totp_url": "https://my-totp-service.com/totp",
  "totp_identifier": "john.doe@example.com",
  "browser_session_id": "<string>",
  "browser_profile_id": "<string>",
  "max_screenshot_scrolls": 123,
  "max_elapsed_time_minutes": 120,
  "extra_http_headers": {},
  "cdp_connect_headers": {},
  "browser_address": "http://127.0.0.1:9222",
  "ai_fallback": true,
  "run_with": "agent",
  "run_metadata": {}
}
'

{
  "run_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "modified_at": "2023-11-07T05:31:56Z",
  "run_type": "<string>",
  "output": {},
  "downloaded_files": [
    {
      "url": "<string>",
      "checksum": "<string>",
      "filename": "<string>",
      "file_size": 123,
      "modified_at": "2023-11-07T05:31:56Z",
      "artifact_id": "<string>"
    }
  ],
  "recording_url": "<string>",
  "recording_archived": false,
  "screenshot_urls": [
    "<string>"
  ],
  "failure_reason": "<string>",
  "queued_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "finished_at": "2023-11-07T05:31:56Z",
  "app_url": "https://app.skyvern.com/tasks/tsk_123",
  "browser_session_id": "pbs_123",
  "browser_profile_id": "bp_123",
  "max_screenshot_scrolls": 123,
  "script_run": {
    "ai_fallback_triggered": false,
    "script_id": "<string>",
    "script_revision_id": "<string>"
  },
  "errors": [
    {}
  ],
  "step_count": 123,
  "run_with": "agent",
  "ai_fallback": true,
  "script_id": "<string>",
  "run_request": {
    "workflow_id": "<string>",
    "parameters": {},
    "title": "<string>",
    "proxy_location": "RESIDENTIAL",
    "webhook_url": "<string>",
    "totp_url": "https://my-totp-service.com/totp",
    "totp_identifier": "john.doe@example.com",
    "browser_session_id": "<string>",
    "browser_profile_id": "<string>",
    "max_screenshot_scrolls": 123,
    "max_elapsed_time_minutes": 120,
    "extra_http_headers": {},
    "cdp_connect_headers": {},
    "browser_address": "http://127.0.0.1:9222",
    "ai_fallback": true,
    "run_with": "agent",
    "run_metadata": {}
  }
}

Headers

x-api-key

string | null

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

x-max-steps-override

integer | null

x-user-agent

string | null

Query Parameters

template

boolean

default:false

Body

application/json

agent_id

string

required

ID of the agent to run. Starts with wpid_. workflow_id is accepted as an alias.

Example:

"wpid_123"

parameters

Parameters · object

Parameters to pass to the workflow

title

string | null

The title for this workflow run

proxy_location

default:RESIDENTIAL

Geographic Proxy location to route the browser traffic through. This is only available in Skyvern Cloud.

Available geotargeting options:

RESIDENTIAL: the default value. Skyvern Cloud uses a random US residential proxy.
RESIDENTIAL_ES: Spain
RESIDENTIAL_IE: Ireland
RESIDENTIAL_GB: United Kingdom
RESIDENTIAL_IN: India
RESIDENTIAL_JP: Japan
RESIDENTIAL_FR: France
RESIDENTIAL_DE: Germany
RESIDENTIAL_NZ: New Zealand
RESIDENTIAL_PH: Philippines
RESIDENTIAL_KR: South Korea
RESIDENTIAL_SA: Saudi Arabia
RESIDENTIAL_ZA: South Africa
RESIDENTIAL_AR: Argentina
RESIDENTIAL_AU: Australia
RESIDENTIAL_BR: Brazil
RESIDENTIAL_TR: Turkey
RESIDENTIAL_CA: Canada
RESIDENTIAL_MX: Mexico
RESIDENTIAL_IT: Italy
RESIDENTIAL_NL: Netherlands
RESIDENTIAL_ISP: ISP proxy
US-CA: California (deprecated, routes through RESIDENTIAL_ISP)
US-NY: New York (deprecated, routes through RESIDENTIAL_ISP)
US-TX: Texas (deprecated, routes through RESIDENTIAL_ISP)
US-FL: Florida (deprecated, routes through RESIDENTIAL_ISP)
US-WA: Washington (deprecated, routes through RESIDENTIAL_ISP)
NONE: No proxy

For self-hosted deployments, you can pass a custom proxy URL as a dict: {"url": "http://user:password@proxy.example.com:8080"} [blocked]. This routes the browser through your own proxy server and takes precedence over any globally configured proxy pool. Can also be a GeoTarget object for granular city/state targeting: {"country": "US", "subdivision": "CA", "city": "San Francisco"}

Available options:

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

webhook_url

string | null

URL to send workflow status updates to after a run is finished. Refer to https://www.skyvern.com/docs/running-tasks/webhooks-faq for webhook questions.

totp_url

string | null

URL that serves TOTP/2FA/MFA codes for Skyvern to use during the workflow run. Refer to https://www.skyvern.com/docs/credentials/totp#option-2-get-code-from-your-endpoint for more details.

Example:

"https://my-totp-service.com/totp"

totp_identifier

string | null

Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to https://www.skyvern.com/docs/credentials/totp#option-3-push-code-to-skyvern for more details.

Example:

"john.doe@example.com"

browser_session_id

string | null

ID of a Skyvern browser session to reuse, having it continue from the current screen state

browser_profile_id

string | null

ID of a browser profile to reuse for this workflow run

max_screenshot_scrolls

integer | null

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

max_elapsed_time_minutes

integer | null

Timeout this workflow run after the configured elapsed runtime in minutes. Maximum runtime is 4 hours.

Required range: 1 <= x <= 240

extra_http_headers

Extra Http Headers · object

The extra HTTP headers for the requests in browser.

Show child attributes

cdp_connect_headers

Cdp Connect Headers · object

HTTP headers attached ONLY to the CDP WebSocket handshake when connecting to a remote browser via browser_address. Use this for browser-provider auth (e.g., x-api-key for Skyvern Cloud, Browserless, or similar). These headers are NEVER forwarded to target websites.

Show child attributes

browser_address

string | null

The CDP address for the workflow run.

Example:

"http://127.0.0.1:9222"

ai_fallback

boolean | null

Whether to fallback to AI if the workflow run fails.

run_with

string | null

Whether to run the workflow with agent or code. Null inherits from the workflow setting.

Example:

"agent"

run_metadata

Run Metadata · object

String key/value metadata to attach to this workflow run for analytics tag filtering.

Show child attributes

Response

Successfully ran agent

run_id

string

required

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

Examples:

"tsk_123"

"tsk_v2_123"

"wr_123"

status

enum<string>

required

Current status of the run

Available options:

created,

queued,

running,

timed_out,

failed,

terminated,

completed,

canceled

Examples:

"created"

"queued"

"running"

"timed_out"

"failed"

"terminated"

"completed"

"canceled"

created_at

string<date-time>

required

Timestamp when this run was created

Example:

"2025-01-01T00:00:00Z"

modified_at

string<date-time>

required

Timestamp when this run was last modified

Example:

"2025-01-01T00:05:00Z"

run_type

string

required

Type of run - always workflow_run for workflow runs

Allowed value: "workflow_run"

output

Output data from the run, if any. Format/schema depends on the data extracted by the run.

downloaded_files

FileInfo · object[] | null

List of files downloaded during the run

Show child attributes

recording_url

string | null

URL to the recording of the run

recording_archived

boolean

default:false

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

screenshot_urls

string[] | null

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

failure_reason

string | null

Reason for failure if the run failed or terminated

queued_at

string<date-time> | null

Timestamp when this run was queued

started_at

string<date-time> | null

Timestamp when this run started execution

finished_at

string<date-time> | null

Timestamp when this run finished

app_url

string | null

URL to the application UI where the run can be viewed

Example:

"https://app.skyvern.com/tasks/tsk_123"

browser_session_id

string | null

ID of the Skyvern persistent browser session used for this run

Example:

"pbs_123"

browser_profile_id

string | null

ID of the browser profile used for this run

Example:

"bp_123"

max_screenshot_scrolls

integer | null

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

script_run

ScriptRunResponse · object

The script run result

Show child attributes

errors

Errors · object[] | null

The errors for the run

step_count

integer | null

Total number of steps executed in this run

run_with

string

default:agent

Whether the workflow run was executed with agent or code

Examples:

"agent"

"code"

ai_fallback

boolean | null

Whether to fallback to AI if code run fails.

script_id

string | null

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

run_request

WorkflowRunRequest · object

The original request parameters used to start this workflow run

Show child attributes

Get run info by id

⌘I