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

Changes

Changed in 7 of the 86 revisions of this API.1111

  • 89037b86e0042See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the optional property // to the response with the status

      response-optional-property-added

  • 830020b643cd2See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the optional property // to the response with the status

      response-optional-property-added

  • bd64e0480f0a3See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the optional property // to the response with the status

      response-optional-property-added

  • b7fa64d357691See the full diff
    • ●

      added the new paused enum value to the response property for the response status

      response-property-enum-value-added

  • cd89b4c6f00411See the full diff
    • ▲

      the /// response property's max was increased from 240.00 to 480.00 for the response status

      response-property-max-increased

    • ○

      the / request property's max was increased from 240.00 to 480.00

      request-property-max-increased

  • e5a0a7c3a5c62See the full diff
    • ○

      api tag Runs added

      api-tag-added

    • ○

      api tag Agents removed

      api-tag-removed

  • 3a3616091b661See the full diff
    • ○

      endpoint added

      endpoint-added

    This revision also has 10 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog