Sign in
Runs

Run an agent

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

reuse_browser_sessionboolean nullable

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

ID of a browser profile to reuse for this workflow run

start_fresh_browserboolean

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_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.

file_idsstring[] nullable

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.

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",
  "file_ids": [
    "file_123456789"
  ]
}

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.

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.

browser_seed_source'override' | 'picked' | 'own_memory' | 'credential' | 'fresh' | 'degraded_fresh'

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

Resolved once at run setup, before any browser creation, for all run types (C-semantics).

  • override: explicit request browser_profile_id (one-run-only pick via API)
  • picked: the workflow's explicit profile pick (workflows.browser_profile_id) — "always start here"
  • own_memory: the workflow's own auto-profile (no pick + persist_browser_session)
  • credential: the run's selected credential's profile (rotation-aware; also the empty-own boot)
  • fresh: no seed profile
  • degraded_fresh: a resolved profile failed to load; ran fresh

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",
    "file_ids": [
      "file_123456789"
    ]
  }
}