Run an agent

Run an agent

POST /v1/run/agents

Run an agent

cURL

curl --request POST \
  --url https://api.skyvern.com/v1/run/agents \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": "wpid_123",
  "parameters": {},
  "title": "<string>",
  "proxy_location": "RESIDENTIAL",
  "webhook_url": "<string>",
  "totp_url": "https://my-totp-service.com/totp",
  "totp_identifier": "[e-mail]",
  "browser_session_id": "<string>",
  "reuse_browser_session": true,
  "browser_profile_id": "<string>",
  "start_fresh_browser": false,
  "max_screenshot_scrolls": 123,
  "max_elapsed_time_minutes": 240,
  "extra_http_headers": {},
  "cdp_connect_headers": {},
  "browser_address": "http://127.0.0.1:9222",
  "ai_fallback": true,
  "run_with": "agent",
  "run_metadata": {},
  "file_ids": [
    "file_123456789"
  ]
}
'

200

{
  "run_id": "tsk_123",
  "status": "created",
  "created_at": "2025-01-01T00:00:00Z",
  "modified_at": "2025-01-01T00:05:00Z",
  "run_type": "workflow_run",
  "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>",
  "browser_seed_source": "credential",
  "run_request": {
    "workflow_id": "wpid_123",
    "parameters": {},
    "title": "<string>",
    "proxy_location": "RESIDENTIAL",
    "webhook_url": "<string>",
    "totp_url": "https://my-totp-service.com/totp",
    "totp_identifier": "[e-mail]",
    "browser_session_id": "<string>",
    "reuse_browser_session": true,
    "browser_profile_id": "<string>",
    "start_fresh_browser": false,
    "max_screenshot_scrolls": 123,
    "max_elapsed_time_minutes": 240,
    "extra_http_headers": {},
    "cdp_connect_headers": {},
    "browser_address": "http://127.0.0.1:9222",
    "ai_fallback": true,
    "run_with": "agent",
    "run_metadata": {},
    "file_ids": [
      "file_123456789"
    ]
  }
}

Headers

x-api-key · string | null

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 | null

Parameters to pass to the workflow

title · string | null

The title for this workflow run

proxy_location · enum<string> GeoTarget · object Proxy Location · object · 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:[e-mail]: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:

"[e-mail]"

browser_session_id · string | null

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

reuse_browser_session · boolean | null

Override whether this run reuses the workflow's managed browser session. Null inherits the workflow setting. Without login credentials, a browser profile key, or a sequential key, reuse is workflow-scoped: every run shares one browser and its signed-in state, so treat the workflow as single-account.

browser_profile_id · string | null

ID of a browser profile to reuse for this workflow run

start_fresh_browser · boolean · default: false

When true, start this run from a fresh, empty browser and ignore any saved browser memory — no memory is read or written. A verified sign-in during the run still updates the credential's saved login.

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. When omitted, the platform default is 240 minutes. The maximum configurable value is 480 minutes.

Required range: 1 <= x <= 480

extra_http_headers · Extra Http Headers · object | null

The extra HTTP headers for the requests in browser.

Show child attributes

cdp_connect_headers · Cdp Connect Headers · object | null

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 | null

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

Show child attributes

file_ids · string[] | null

Ids of files uploaded through POST /v1/upload_file to attach to this run. Skyvern deletes an attached file as soon as the run finishes, so there is nothing to clean up afterwards. Reference an attached file by its id anywhere a file URL is accepted (for example in parameters or in the prompt) and no presigned URL is ever created for it. A file can be attached to one run at a time, and must not already be deleted.

Maximum array length: 50

Example:

["file_123456789"]

Response

200

application/json

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, paused, timed_out, failed, terminated, completed, canceled

Examples:

"created"

"queued"

"running"

"paused"

"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 · object any[] string

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 | null

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.

browser_seed_source · enum<string> | null

Which layer of the seed-precedence chain seeded this run's browser (provenance).

Available options: override, picked, own_memory, credential, fresh, degraded_fresh

Example:

"credential"

run_request · WorkflowRunRequest · object | null

The original request parameters used to start this workflow run

Show child attributes