Runs

Run an agent

post/v1/run/agents

Query parameters

templateboolean

Headers

x-api-keystring nullable

x-max-steps-overrideinteger nullable

x-user-agentstring nullable

Request body

agent_idstring required

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

parametersobject nullable

Parameters to pass to the workflow

titlestring nullable

The title for this workflow run

webhook_urlstring nullable

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_urlstring nullable

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.

totp_identifierstring nullable

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.

browser_session_idstring nullable

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

browser_profile_idstring nullable

ID of a browser profile to reuse for this workflow 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.

max_elapsed_time_minutesinteger nullable

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.

extra_http_headersobject nullable

The extra HTTP headers for the requests in browser.

cdp_connect_headersobject nullable

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.

browser_addressstring nullable

The CDP address for the workflow run.

ai_fallbackboolean nullable

Whether to fallback to AI if the workflow run fails.

run_withstring nullable

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

run_metadataobject nullable

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

Example request

{
  "agent_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"
}

Response

Successfully ran agent

run_idstring required

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

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"
  }
}

Changes

Changed in 4 of the 63 revisions of this API.114

Jul 20, 2026645819945b7b1See the full diff
- ●
  added the new paused enum value to the status response property for the response status 200
  response-property-enum-value-added
Jun 15, 2026cd89b4c6f00411See the full diff
- ▲
  the run_request/anyOf[subschema #1: WorkflowRunRequest]/max_elapsed_time_minutes/anyOf[subschema #1]/ response property's max was increased from 240.00 to 480.00 for the response status 200
  response-property-max-increased
- ○
  the max_elapsed_time_minutes/anyOf[subschema #1]/ request property's max was increased from 240.00 to 480.00
  request-property-max-increased
Jun 13, 2026e7044f43e57e2See the full diff
- ○
  api tag Runs added
  api-tag-added
- ○
  api tag Agents removed
  api-tag-removed
Jun 7, 2026e37d309fc58f1See the full diff
- ○
  endpoint added
  endpoint-added

Full history