Agents

Run a task

post/v1/run/tasks

Headers

x-api-keystring nullable

x-user-agentstring nullable

Request body

promptstring required

The goal or task description for Skyvern to accomplish

urlstring nullable

The starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL

titlestring nullable

The title for the task

error_code_mappingobject nullable

Custom mapping of error codes to error messages if Skyvern encounters an error.

max_stepsinteger nullable

Maximum number of steps the task can take. Task will fail if it exceeds this number. Cautions: you are charged per step so please set this number to a reasonable value. Contact sales@skyvern.com for custom pricing.

webhook_urlstring nullable

After a run is finished, send an update to this URL. Refer to https://www.skyvern.com/docs/running-tasks/webhooks-faq 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.

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.

browser_session_idstring nullable

Run the task or workflow in the specific Skyvern browser session. Having a browser session can persist the real-time state of the browser, so that the next run can continue from where the previous run left off.

browser_profile_idstring nullable

ID of a browser profile to reuse for this task

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.

modelobject nullable

Optional model configuration.

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.

publish_workflowboolean

Deprecated. Whether to publish a skyvern-2.0 task as a reusable workflow. For backwards compatibility, this routes the request through the legacy skyvern-2.0 publish path. Prefer creating reusable workflows through the workflow APIs.

include_action_history_in_verificationboolean nullable

Whether to include action history when verifying that the task is complete

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.

browser_addressstring nullable

The CDP address for the task.

run_withstring nullable

Whether to run the task with agent or code. Null means use the default.

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

{
  "prompt": "Find the top 3 posts on Hacker News.",
  "url": "https://www.hackernews.com",
  "title": "The title of my first skyvern task",
  "proxy_location": {
    "country": "US",
    "subdivision": "CA",
    "city": "New York"
  },
  "error_code_mapping": {
    "login_failed": "The login credentials are incorrect or the account is locked"
  },
  "max_steps": 10,
  "webhook_url": "https://my-site.com/webhook",
  "totp_identifier": "john.doe@example.com",
  "totp_url": "https://my-totp-service.com/totp",
  "browser_session_id": "pbs_123",
  "browser_address": "http://127.0.0.1:9222",
  "run_with": "agent",
  "file_ids": [
    "file_123456789"
  ]
}

Response

Successfully run task

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

Types of a task run - task_v1, task_v2, openai_cua, anthropic_cua, ui_tars

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_request": {
    "prompt": "Find the top 3 posts on Hacker News.",
    "url": "https://www.hackernews.com",
    "title": "The title of my first skyvern task",
    "proxy_location": {
      "country": "US",
      "subdivision": "CA",
      "city": "New York"
    },
    "error_code_mapping": {
      "login_failed": "The login credentials are incorrect or the account is locked"
    },
    "max_steps": 10,
    "webhook_url": "https://my-site.com/webhook",
    "totp_identifier": "john.doe@example.com",
    "totp_url": "https://my-totp-service.com/totp",
    "browser_session_id": "pbs_123",
    "browser_address": "http://127.0.0.1:9222",
    "run_with": "agent",
    "file_ids": [
      "file_123456789"
    ]
  }
}

Changes

Changed in 13 of the 86 revisions of this API.352555

Aug 22, 202689037b86e0042See 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
Aug 13, 20260c5e6f1a3df921See the full diff
- ●
  added the new skyvern-3.0 enum value to the // response property for the response status
  response-property-enum-value-added
- ●
  added the new task_v3 enum value to the response property for the response status
  response-property-enum-value-added
- ○
  added the new skyvern-3.0 enum value to the request property
  request-property-enum-value-added
Jul 24, 2026bd64e0480f0a4See the full diff
- ○
  added the new optional request property
  new-optional-request-property
- ○
  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
Jul 20, 2026b7fa64d357691See the full diff
- ●
  added the new paused enum value to the response property for the response status
  response-property-enum-value-added
Jun 8, 20263a3616091b66352133See the full diff
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property // became not nullable
  request-property-became-not-nullable
- ▲
  the request property // became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  response property app_url list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property browser_profile_id list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property browser_session_id list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property downloaded_files list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property errors list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property failure_reason list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property finished_at list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property max_screenshot_scrolls list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property output list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property queued_at list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property recording_url list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property screenshot_urls list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property started_at list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property step_count list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  the response's property type changed from object to no type for status
  response-property-type-changed
- ▲
  the response's property type changed from object to no type for status
  response-property-type-changed
- ▲
  removed the required property / from the response with the status
  response-required-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ●
  removed the optional property / from the response with the status
  response-optional-property-removed
- ○
  api tag Agents added
  api-tag-added
- ○
  api tag Agent removed
  api-tag-removed
- ○
  added the new optional request property
  new-optional-request-property
- ○
  header request parameter x-api-key list-of-types was widened by adding types null
  request-parameter-list-of-types-widened
- ○
  header request parameter x-user-agent list-of-types was widened by adding types null
  request-parameter-list-of-types-widened
- ○
  for the header request parameter x-api-key, the type was generalized from string to no type
  request-parameter-type-generalized
- ○
  for the header request parameter x-user-agent, the type was generalized from string to no type
  request-parameter-type-generalized
- ○
  added subschema #4 to the request property anyOf list
  request-property-any-of-added
- ○
  added the new RESIDENTIAL_KR enum value to the request property /
  request-property-enum-value-added
- ○
  added the new RESIDENTIAL_SA enum value to the request property /
  request-property-enum-value-added
- ○
  added the new yutori-navigator enum value to the request property
  request-property-enum-value-added
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property // list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property // list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  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
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added subschema #2 to the response property anyOf list for the response status
  response-property-any-of-added
- ○
  added subschema #2 to the response property anyOf list for the response status
  response-property-any-of-added
This revision also has 10 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
May 26, 2026c1f6a1464e644See the full diff
- ○
  the request property default value changed from skyvern-2.0 to skyvern-1.0
  request-property-default-value-changed
- ○
  request property deprecated
  request-property-deprecated
- ○
  the response's property default value changed from skyvern-2.0 to skyvern-1.0 for the status
  response-property-default-value-changed
- ○
  response property run_request/publish_workflow deprecated
  response-property-deprecated
May 25, 2026ec25ca3a20bb1See the full diff
- ●
  added the new yutori_navigator enum value to the response property for the response status
  response-property-enum-value-added
Apr 24, 20263b8ad911785b2See the full diff
- ○
  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
Apr 23, 2026a8899e7707c42See the full diff
- ○
  the request property default value changed from skyvern-1.0 to skyvern-2.0
  request-property-default-value-changed
- ○
  the response's property default value changed from skyvern-1.0 to skyvern-2.0 for the status
  response-property-default-value-changed
This revision also has 7 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Apr 22, 2026446a00cd1eec2See the full diff
- ○
  the request property default value changed from skyvern-2.0 to skyvern-1.0
  request-property-default-value-changed
- ○
  the response's property default value changed from skyvern-2.0 to skyvern-1.0 for the status
  response-property-default-value-changed

Full history (13 revisions)