Skyvern: Tasks schemas
11 Skyvern schemas with complete fields and constraints.
← Tasks operations · All schemas
File Download Task — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
browser_address | JSON | Optional | The CDP address for the task. |
browser_address (anyOf 1) | string | Alternative | |
browser_address (anyOf 2) | null | Alternative | |
browser_profile_id | JSON | Optional | ID of a browser profile to reuse for this run |
browser_profile_id (anyOf 1) | string | Alternative | |
browser_profile_id (anyOf 2) | null | Alternative | |
browser_session_id | JSON | Optional | ID of the browser session to use, which is prefixed by `pbs_` e.g. `pbs_123456` |
browser_session_id (anyOf 1) | string | Alternative | |
browser_session_id (anyOf 2) | null | Alternative | |
cdp_connect_headers | JSON | Optional | HTTP headers attached ONLY to the CDP WebSocket handshake when connecting to a remote browser via browser_address. Never forwarded to target websites. |
cdp_connect_headers (anyOf 1) | object | Alternative | Additional keys: see wildcard field |
cdp_connect_headers (anyOf 1).* | string | Additional keys | |
cdp_connect_headers (anyOf 2) | null | Alternative | |
download_suffix | JSON | Optional | Complete filename for the downloaded file. Supports {{ original_filename }}, which keeps the name the site gave the file, so {{ original_filename }} alone preserves it and prefix_{{ original_filename }} prefixes it. The source extension is used unless the configured filename includes an extension, which overrides it. {{ original_filename }} must be a standalone interpolation without filters or other transformations. |
download_suffix (anyOf 1) | string | Alternative | |
download_suffix (anyOf 2) | null | Alternative | |
download_timeout | JSON | Optional | Timeout in seconds for the download operation |
download_timeout (anyOf 1) | number | Alternative | |
download_timeout (anyOf 2) | null | Alternative | |
extra_http_headers | JSON | Optional | Additional HTTP headers to include in requests |
extra_http_headers (anyOf 1) | object | Alternative | Additional keys: see wildcard field |
extra_http_headers (anyOf 1).* | string | Additional keys | |
extra_http_headers (anyOf 2) | null | Alternative | |
max_screenshot_scrolling_times | JSON | Optional | Maximum number of times to scroll for screenshots |
max_screenshot_scrolling_times (anyOf 1) | integer | Alternative | |
max_screenshot_scrolling_times (anyOf 2) | null | Alternative | |
max_steps_per_run | JSON | Optional | Maximum number of steps to execute |
max_steps_per_run (anyOf 1) | integer | Alternative | |
max_steps_per_run (anyOf 2) | null | Alternative | |
navigation_goal | string | Required within parent | Instructions for navigating to and downloading the file |
proxy_location | JSON | Optional | Proxy location to use |
proxy_location (anyOf 1) | string | Alternative | One of: 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 |
proxy_location (anyOf 2) | null | Alternative | |
start_fresh_browser | boolean | Optional | 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. Default: false |
totp_identifier | JSON | Optional | Identifier for TOTP (Time-based One-Time Password) if required |
totp_identifier (anyOf 1) | string | Alternative | |
totp_identifier (anyOf 2) | null | Alternative | |
totp_url | JSON | Optional | TOTP URL to fetch one-time passwords |
totp_url (anyOf 1) | string | Alternative | |
totp_url (anyOf 2) | null | Alternative | |
url | JSON | Optional | Website URL |
url (anyOf 1) | string | Alternative | |
url (anyOf 2) | null | Alternative | |
webhook_url | JSON | Optional | Webhook URL to send status updates |
webhook_url (anyOf 1) | string | Alternative | |
webhook_url (anyOf 2) | null | Alternative |
Login Task — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
azure_vault_name | JSON | Optional | Azure Vault Name |
azure_vault_name (anyOf 1) | string | Alternative | |
azure_vault_name (anyOf 2) | null | Alternative | |
azure_vault_password_key | JSON | Optional | Azure Vault password key |
azure_vault_password_key (anyOf 1) | string | Alternative | |
azure_vault_password_key (anyOf 2) | null | Alternative | |
azure_vault_totp_secret_key | JSON | Optional | Azure Vault TOTP secret key |
azure_vault_totp_secret_key (anyOf 1) | string | Alternative | |
azure_vault_totp_secret_key (anyOf 2) | null | Alternative | |
azure_vault_username_key | JSON | Optional | Azure Vault username key |
azure_vault_username_key (anyOf 1) | string | Alternative | |
azure_vault_username_key (anyOf 2) | null | Alternative | |
bitwarden_collection_id | JSON | Optional | Bitwarden collection ID. You can find it in the Bitwarden collection URL. e.g. `https://vault.bitwarden.com/vaults/collection_id/items` |
bitwarden_collection_id (anyOf 1) | string | Alternative | |
bitwarden_collection_id (anyOf 2) | null | Alternative | |
bitwarden_item_id | JSON | Optional | Bitwarden item ID |
bitwarden_item_id (anyOf 1) | string | Alternative | |
bitwarden_item_id (anyOf 2) | null | Alternative | |
browser_address | JSON | Optional | The CDP address for the task. |
browser_address (anyOf 1) | string | Alternative | |
browser_address (anyOf 2) | null | Alternative | |
browser_profile_id | JSON | Optional | ID of a browser profile to reuse for this run |
browser_profile_id (anyOf 1) | string | Alternative | |
browser_profile_id (anyOf 2) | null | Alternative | |
browser_session_id | JSON | Optional | ID of the browser session to use, which is prefixed by `pbs_` e.g. `pbs_123456` |
browser_session_id (anyOf 1) | string | Alternative | |
browser_session_id (anyOf 2) | null | Alternative | |
cdp_connect_headers | JSON | Optional | HTTP headers attached ONLY to the CDP WebSocket handshake when connecting to a remote browser via browser_address. Never forwarded to target websites. |
cdp_connect_headers (anyOf 1) | object | Alternative | Additional keys: see wildcard field |
cdp_connect_headers (anyOf 1).* | string | Additional keys | |
cdp_connect_headers (anyOf 2) | null | Alternative | |
credential_id | JSON | Optional | ID of the Skyvern credential to use for login. |
credential_id (anyOf 1) | string | Alternative | |
credential_id (anyOf 2) | null | Alternative | |
credential_type | string | Required within parent | Where to get the credential from One of: skyvern, bitwarden, 1password, azure_vault |
extra_http_headers | JSON | Optional | Additional HTTP headers to include in requests |
extra_http_headers (anyOf 1) | object | Alternative | Additional keys: see wildcard field |
extra_http_headers (anyOf 1).* | string | Additional keys | |
extra_http_headers (anyOf 2) | null | Alternative | |
max_screenshot_scrolling_times | JSON | Optional | Maximum number of times to scroll for screenshots |
max_screenshot_scrolling_times (anyOf 1) | integer | Alternative | |
max_screenshot_scrolling_times (anyOf 2) | null | Alternative | |
onepassword_item_id | JSON | Optional | 1Password item ID |
onepassword_item_id (anyOf 1) | string | Alternative | |
onepassword_item_id (anyOf 2) | null | Alternative | |
onepassword_totp_field_name | JSON | Optional | 1Password item field id or label to treat as the TOTP secret, overriding 1Password's own field-type detection |
onepassword_totp_field_name (anyOf 1) | string | Alternative | |
onepassword_totp_field_name (anyOf 2) | null | Alternative | |
onepassword_vault_id | JSON | Optional | 1Password vault ID |
onepassword_vault_id (anyOf 1) | string | Alternative | |
onepassword_vault_id (anyOf 2) | null | Alternative | |
prompt | JSON | Optional | Login instructions. Skyvern has default prompt/instruction for login if this field is not provided. |
prompt (anyOf 1) | string | Alternative | |
prompt (anyOf 2) | null | Alternative | |
proxy_location | JSON | Optional | Proxy location to use |
proxy_location (anyOf 1) | string | Alternative | One of: 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 |
proxy_location (anyOf 2) | null | Alternative | |
start_fresh_browser | boolean | Optional | 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. Default: false |
totp_identifier | JSON | Optional | Identifier for TOTP (Time-based One-Time Password) if required |
totp_identifier (anyOf 1) | string | Alternative | |
totp_identifier (anyOf 2) | null | Alternative | |
totp_url | JSON | Optional | TOTP URL to fetch one-time passwords |
totp_url (anyOf 1) | string | Alternative | |
totp_url (anyOf 2) | null | Alternative | |
url | JSON | Optional | Website URL |
url (anyOf 1) | string | Alternative | |
url (anyOf 2) | null | Alternative | |
webhook_url | JSON | Optional | Webhook URL to send status updates |
webhook_url (anyOf 1) | string | Alternative | |
webhook_url (anyOf 2) | null | Alternative |
Login Task — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
ai_fallback | JSON | Optional | Whether to fallback to AI if code run fails. |
ai_fallback (anyOf 1) | boolean | Alternative | |
ai_fallback (anyOf 2) | null | Alternative | |
app_url | JSON | Optional | URL to the application UI where the run can be viewed |
app_url (anyOf 1) | string | Alternative | |
app_url (anyOf 2) | null | Alternative | |
attempt | JSON | Optional | |
attempt (anyOf 1) | integer | Alternative | One-based number of the current workflow run attempt Default: 1 |
attempt (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
attempts | array | Optional | Attempts recorded for this workflow run |
attempts[] | Model | Each item | Expand Login Task — response body — attempts item |
browser_profile_id | JSON | Optional | ID of the browser profile used for this run |
browser_profile_id (anyOf 1) | string | Alternative | |
browser_profile_id (anyOf 2) | null | Alternative | |
browser_seed_source | JSON | Optional | Which layer of the seed-precedence chain seeded this run's browser (provenance). |
browser_seed_source (anyOf 1) | Model | Alternative | Expand Login Task — response body — browser seed source string |
browser_seed_source (anyOf 2) | null | Alternative | |
browser_session_id | JSON | Optional | ID of the Skyvern persistent browser session used for this run |
browser_session_id (anyOf 1) | string | Alternative | |
browser_session_id (anyOf 2) | null | Alternative | |
browser_settings_receipt | JSON | Optional | The timezone the run's browser reported against the one its workflow version requested. Null when the version requests no browser settings or the browser has not been measured yet. |
browser_settings_receipt (anyOf 1) | Model | Alternative | Expand Login Task — response body — browser_settings_receipt / source: workflow version, session request, existing session, status: verified, mismatch, unapplied, unknown |
browser_settings_receipt (anyOf 2) | null | Alternative | |
created_at | string | Required within parent | Timestamp when this run was created Format: date-time |
downloaded_files | JSON | Optional | List of files downloaded during the run |
downloaded_files (anyOf 1) | array | Alternative | |
downloaded_files (anyOf 1)[] | Model | Each item | Expand Get a session — response body — recordings array item |
downloaded_files (anyOf 2) | null | Alternative | |
errors | JSON | Optional | The errors for the run |
errors (anyOf 1) | array | Alternative | |
errors (anyOf 1)[] | object | Each item | Additional keys: allowed |
errors (anyOf 2) | null | Alternative | |
failure_reason | JSON | Optional | Reason for failure if the run failed or terminated |
failure_reason (anyOf 1) | string | Alternative | |
failure_reason (anyOf 2) | null | Alternative | |
finished_at | JSON | Optional | Timestamp when this run finished |
finished_at (anyOf 1) | string | Alternative | Format: date-time |
finished_at (anyOf 2) | null | Alternative | |
max_screenshot_scrolls | JSON | Optional | The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot |
max_screenshot_scrolls (anyOf 1) | JSON | Alternative | |
max_screenshot_scrolls (anyOf 1) (anyOf 1) | integer | Alternative | |
max_screenshot_scrolls (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
max_screenshot_scrolls (anyOf 2) | null | Alternative | |
modified_at | string | Required within parent | Timestamp when this run was last modified Format: date-time |
next_attempt_at | JSON | Optional | Timestamp when the next workflow run attempt is scheduled |
next_attempt_at (anyOf 1) | string | Alternative | Format: date-time |
next_attempt_at (anyOf 2) | null | Alternative | |
output | JSON | Optional | Output data from the run, if any. Format/schema depends on the data extracted by the run. |
output (anyOf 1) | object | Alternative | Additional keys: allowed |
output (anyOf 2) | array | Alternative | |
output (anyOf 2)[] | JSON | Each item | |
output (anyOf 3) | string | Alternative | |
output (anyOf 4) | null | Alternative | |
queued_at | JSON | Optional | Timestamp when this run was queued |
queued_at (anyOf 1) | string | Alternative | Format: date-time |
queued_at (anyOf 2) | null | Alternative | |
recording_archived | boolean | Optional | True when the recording exists but has been archived to cold storage and is not currently accessible. Default: false |
recording_url | JSON | Optional | URL to the recording of the run |
recording_url (anyOf 1) | string | Alternative | |
recording_url (anyOf 2) | null | Alternative | |
retry_pending | boolean | Optional | Whether another attempt is scheduled for this workflow run Default: false |
run_id | string | Required within parent | Unique identifier for this run. Run ID starts with `tsk_` for task runs and `wr_` for workflow runs. |
run_request | JSON | Optional | The original request parameters used to start this workflow run |
run_request (anyOf 1) | Model | Alternative | Expand Login Task — response body — run request ai fallback, browser address, browser profile id, browser session id, browser type, cdp connect headers, extra http headers, file ids, max elapsed time minutes, max screenshot scrolls, parameters, proxy location, reuse browser session, run metadata, run with, start fresh browser, title, totp identifier, totp url, webhook url, workflow id |
run_request (anyOf 2) | null | Alternative | |
run_type | string | Required within parent | Type of run - always workflow_run for workflow runs Must equal: workflow_run |
run_with | string | Optional | Whether the workflow run was executed with agent or code Default: agent |
screenshot_urls | JSON | Optional | List of last n screenshot URLs in reverse chronological order - the first one the list is the latest screenshot. |
screenshot_urls (anyOf 1) | array | Alternative | |
screenshot_urls (anyOf 1)[] | string | Each item | |
screenshot_urls (anyOf 2) | null | Alternative | |
script_id | JSON | Optional | ID of the cached script used for this workflow run, if any. |
script_id (anyOf 1) | string | Alternative | |
script_id (anyOf 2) | null | Alternative | |
script_run | JSON | Optional | The script run result |
script_run (anyOf 1) | Model | Alternative | Expand Login Task — response body — script run ai fallback triggered, script id, script revision id |
script_run (anyOf 2) | null | Alternative | |
started_at | JSON | Optional | Timestamp when this run started execution |
started_at (anyOf 1) | string | Alternative | Format: date-time |
started_at (anyOf 2) | null | Alternative | |
status | string | Required within parent | Current status of the run Known values: created, queued, running, paused, timed_out, failed, terminated, completed, canceled |
step_count | JSON | Optional | Total number of steps executed in this run |
step_count (anyOf 1) | JSON | Alternative | |
step_count (anyOf 1) (anyOf 1) | integer | Alternative | |
step_count (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
step_count (anyOf 2) | null | Alternative |
Referenced models: Login Task — response body — browser seed source string, Login Task — response body — browser_settings_receipt / source: workflow version, session request, existing session, status: verified, mismatch, unapplied, unknown, Get a session — response body — recordings array item, Login Task — response body — script run ai fallback triggered, script id, script revision id, Login Task — response body — attempts item, Login Task — response body — run request ai fallback, browser address, browser profile id, browser session id, browser type, cdp connect headers, extra http headers, file ids, max elapsed time minutes, max screenshot scrolls, parameters, proxy location, reuse browser session, run metadata, run with, start fresh browser, title, totp identifier, totp url, webhook url, workflow id
Login Task — response body — attempts item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
attempt_number | JSON | Required within parent | |
attempt_number (anyOf 1) | integer | Alternative | One-based number of this workflow run attempt |
attempt_number (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
decision_reason | JSON | Optional | Reason recorded for the retry decision |
decision_reason (anyOf 1) | string | Alternative | |
decision_reason (anyOf 2) | null | Alternative | |
error_codes | array | Optional | Error codes reported by this attempt |
error_codes[] | string | Each item | |
failure_reason | JSON | Optional | Reason for failure, if the attempt failed |
failure_reason (anyOf 1) | string | Alternative | |
failure_reason (anyOf 2) | null | Alternative | |
finished_at | JSON | Optional | Timestamp when this attempt finished |
finished_at (anyOf 1) | string | Alternative | Format: date-time |
finished_at (anyOf 2) | null | Alternative | |
next_attempt_at | JSON | Optional | Timestamp when the next attempt is scheduled |
next_attempt_at (anyOf 1) | string | Alternative | Format: date-time |
next_attempt_at (anyOf 2) | null | Alternative | |
retry_decision | JSON | Optional | Retry decision recorded for this attempt |
retry_decision (anyOf 1) | string | Alternative | |
retry_decision (anyOf 2) | null | Alternative | |
started_at | JSON | Optional | Timestamp when this attempt started |
started_at (anyOf 1) | string | Alternative | Format: date-time |
started_at (anyOf 2) | null | Alternative | |
status | string | Required within parent | Status of this workflow run attempt Known values: created, queued, running, paused, timed_out, failed, terminated, completed, canceled |
webhook_sent_at | JSON | Optional | Timestamp when the webhook for this attempt was sent |
webhook_sent_at (anyOf 1) | string | Alternative | Format: date-time |
webhook_sent_at (anyOf 2) | null | Alternative |
Login Task — response body — browser seed source string
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | string | Root | 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 Known values: override, picked, own_memory, credential, fresh, degraded_fresh |
Login Task — response body — browser_settings_receipt / source: workflow version, session request, existing session, status: verified, mismatch, unapplied, unknown
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
actual_timezone_id | JSON | Optional | The timezone the browser reported when measured, or null when it could not be measured. |
actual_timezone_id (anyOf 1) | string | Alternative | |
actual_timezone_id (anyOf 2) | null | Alternative | |
requested_timezone_id | string | Required within parent | The timezone that was requested. |
source | string | Required within parent | Where the requested setting came from. Known values: workflow_version, session_request, existing_session |
status | string | Required within parent | `verified` when the browser reported the requested timezone or an IANA alias of it (Chromium reports `Asia/Calcutta` for `Asia/Kolkata`), `mismatch` when it reported another zone, `unapplied` when the browser already existed and was left unchanged, `unknown` when it could not be measured. Known values: verified, mismatch, unapplied, unknown |
warning | JSON | Optional | |
warning (anyOf 1) | string | Alternative | |
warning (anyOf 2) | null | Alternative |
Login Task — response body — run request ai fallback, browser address, browser profile id, browser session id, browser type, cdp connect headers, extra http headers, file ids, max elapsed time minutes, max screenshot scrolls, parameters, proxy location, reuse browser session, run metadata, run with, start fresh browser, title, totp identifier, totp url, webhook url, workflow id
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
ai_fallback | JSON | Optional | Whether to fallback to AI if the workflow run fails. |
ai_fallback (anyOf 1) | boolean | Alternative | |
ai_fallback (anyOf 2) | null | Alternative | |
browser_address | JSON | Optional | The CDP address for the workflow run. |
browser_address (anyOf 1) | string | Alternative | |
browser_address (anyOf 2) | null | Alternative | |
browser_profile_id | JSON | Optional | ID of a browser profile to reuse for this workflow run |
browser_profile_id (anyOf 1) | string | Alternative | |
browser_profile_id (anyOf 2) | null | Alternative | |
browser_session_id | JSON | Optional | ID of a Skyvern browser session to reuse, having it continue from the current screen state |
browser_session_id (anyOf 1) | string | Alternative | |
browser_session_id (anyOf 2) | null | Alternative | |
browser_type | JSON | Optional | Browser engine for this run, one of the supported browser types (e.g. msedge, chrome, stealth-chromium). Overrides the workflow-level setting. Null inherits from the workflow. |
browser_type (anyOf 1) | string | Alternative | |
browser_type (anyOf 2) | null | Alternative | |
cdp_connect_headers | JSON | Optional | 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. |
cdp_connect_headers (anyOf 1) | object | Alternative | Additional keys: see wildcard field |
cdp_connect_headers (anyOf 1).* | string | Additional keys | |
cdp_connect_headers (anyOf 2) | null | Alternative | |
extra_http_headers | JSON | Optional | The extra HTTP headers for the requests in browser. |
extra_http_headers (anyOf 1) | object | Alternative | Additional keys: see wildcard field |
extra_http_headers (anyOf 1).* | string | Additional keys | |
extra_http_headers (anyOf 2) | null | Alternative | |
file_ids | JSON | Optional | 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. |
file_ids (anyOf 1) | array | Alternative | Maximum items: 50 |
file_ids (anyOf 1)[] | string | Each item | |
file_ids (anyOf 2) | null | Alternative | |
max_elapsed_time_minutes | JSON | Optional | 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. |
max_elapsed_time_minutes (anyOf 1) | JSON | Alternative | |
max_elapsed_time_minutes (anyOf 1) (anyOf 1) | integer | Alternative | Maximum: 480.0 Minimum: 1.0 |
max_elapsed_time_minutes (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
max_elapsed_time_minutes (anyOf 2) | null | Alternative | |
max_screenshot_scrolls | JSON | Optional | The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot. |
max_screenshot_scrolls (anyOf 1) | JSON | Alternative | |
max_screenshot_scrolls (anyOf 1) (anyOf 1) | integer | Alternative | |
max_screenshot_scrolls (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
max_screenshot_scrolls (anyOf 2) | null | Alternative | |
parameters | JSON | Optional | Parameters to pass to the workflow |
parameters (anyOf 1) | object | Alternative | Additional keys: allowed |
parameters (anyOf 2) | null | Alternative | |
proxy_location | JSON | Optional | 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:password@proxy.example:8080"}. 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"} Default: RESIDENTIAL |
proxy_location (anyOf 1) | Model | Alternative | Expand Update an agent — response body — proxy location string |
proxy_location (anyOf 2) | Model | Alternative | Expand Update an agent — response body — proxy location city, country, is ISP, subdivision |
proxy_location (anyOf 3) | object | Alternative | Additional keys: allowed |
proxy_location (anyOf 4) | null | Alternative | |
reuse_browser_session | JSON | Optional | 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. |
reuse_browser_session (anyOf 1) | boolean | Alternative | |
reuse_browser_session (anyOf 2) | null | Alternative | |
run_metadata | JSON | Optional | String key/value metadata to attach to this workflow run for analytics tag filtering. |
run_metadata (anyOf 1) | object | Alternative | Additional keys: see wildcard field |
run_metadata (anyOf 1).* | string | Additional keys | |
run_metadata (anyOf 2) | null | Alternative | |
run_with | JSON | Optional | Whether to run the workflow with agent or code. Null inherits from the workflow setting. |
run_with (anyOf 1) | string | Alternative | |
run_with (anyOf 2) | null | Alternative | |
start_fresh_browser | boolean | Optional | 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. Default: false |
title | JSON | Optional | The title for this workflow run |
title (anyOf 1) | string | Alternative | |
title (anyOf 2) | null | Alternative | |
totp_identifier | JSON | Optional | Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to https://www.skyvern.com/docs/credentials#push-a-code for more details. |
totp_identifier (anyOf 1) | string | Alternative | |
totp_identifier (anyOf 2) | null | Alternative | |
totp_url | JSON | Optional | URL that serves TOTP/2FA/MFA codes for Skyvern to use during the workflow run. Refer to https://www.skyvern.com/docs/credentials#let-skyvern-fetch-codes-from-your-endpoint for more details. |
totp_url (anyOf 1) | string | Alternative | |
totp_url (anyOf 2) | null | Alternative | |
webhook_url | JSON | Optional | 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. |
webhook_url (anyOf 1) | string | Alternative | |
webhook_url (anyOf 2) | null | Alternative | |
workflow_id | string | Required within parent | ID of the agent to run. Starts with `wpid_`. `workflow_id` is accepted as an alias. |
Referenced models: Update an agent — response body — proxy location city, country, is ISP, subdivision, Update an agent — response body — proxy location string
Login Task — response body — script run ai fallback triggered, script id, script revision id
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
ai_fallback_triggered | boolean | Optional | Default: false |
script_id | JSON | Optional | |
script_id (anyOf 1) | string | Alternative | |
script_id (anyOf 2) | null | Alternative | |
script_revision_id | JSON | Optional | |
script_revision_id (anyOf 1) | string | Alternative | |
script_revision_id (anyOf 2) | null | Alternative |
Run a task — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
browser_address | JSON | Optional | The CDP address for the task. |
browser_address (anyOf 1) | string | Alternative | |
browser_address (anyOf 2) | null | Alternative | |
browser_profile_id | JSON | Optional | ID of a browser profile to reuse for this task |
browser_profile_id (anyOf 1) | string | Alternative | |
browser_profile_id (anyOf 2) | null | Alternative | |
browser_session_id | JSON | Optional | 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_session_id (anyOf 1) | string | Alternative | |
browser_session_id (anyOf 2) | null | Alternative | |
cdp_connect_headers | JSON | Optional | 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. |
cdp_connect_headers (anyOf 1) | object | Alternative | Additional keys: see wildcard field |
cdp_connect_headers (anyOf 1).* | string | Additional keys | |
cdp_connect_headers (anyOf 2) | null | Alternative | |
data_extraction_schema | JSON | Optional | The schema for data to be extracted from the webpage. If you're looking for consistent data schema being returned by the agent, it's highly recommended to use https://json-schema.org/. |
data_extraction_schema (anyOf 1) | object | Alternative | Additional keys: allowed |
data_extraction_schema (anyOf 2) | array | Alternative | |
data_extraction_schema (anyOf 2)[] | JSON | Each item | |
data_extraction_schema (anyOf 3) | string | Alternative | |
data_extraction_schema (anyOf 4) | null | Alternative | |
engine | string | Optional | The engine that powers the agent task. The default value is `skyvern-1.0`, which is good for simple tasks like filling a form, or searching for information on Google. `skyvern-2.0` remains available for existing V2 workflows and explicitly requested V2 task runs. The `openai-cua` engine uses OpenAI's CUA model. The `anthropic-cua` uses Anthropic's Claude Sonnet 3.7 model with the computer use tool. One of: skyvern-1.0, skyvern-2.0, skyvern-3.0, openai-cua, anthropic-cua, ui-tars, yutori-navigator Default: skyvern-1.0 |
error_code_mapping | JSON | Optional | Custom mapping of error codes to error messages if Skyvern encounters an error. |
error_code_mapping (anyOf 1) | object | Alternative | Additional keys: see wildcard field |
error_code_mapping (anyOf 1).* | string | Additional keys | |
error_code_mapping (anyOf 2) | null | Alternative | |
extra_http_headers | JSON | Optional | The extra HTTP headers for the requests in browser. |
extra_http_headers (anyOf 1) | object | Alternative | Additional keys: see wildcard field |
extra_http_headers (anyOf 1).* | string | Additional keys | |
extra_http_headers (anyOf 2) | null | Alternative | |
file_ids | JSON | Optional | 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. |
file_ids (anyOf 1) | array | Alternative | Maximum items: 50 |
file_ids (anyOf 1)[] | string | Each item | |
file_ids (anyOf 2) | null | Alternative | |
include_action_history_in_verification | JSON | Optional | Whether to include action history when verifying that the task is complete Default: false |
include_action_history_in_verification (anyOf 1) | boolean | Alternative | |
include_action_history_in_verification (anyOf 2) | null | Alternative | |
max_screenshot_scrolls | JSON | Optional | The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot. |
max_screenshot_scrolls (anyOf 1) | integer | Alternative | |
max_screenshot_scrolls (anyOf 2) | null | Alternative | |
max_steps | JSON | Optional | 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 at skyvern.com for custom pricing. |
max_steps (anyOf 1) | integer | Alternative | |
max_steps (anyOf 2) | null | Alternative | |
model | JSON | Optional | Optional model configuration. |
model (anyOf 1) | object | Alternative | Additional keys: allowed |
model (anyOf 2) | null | Alternative | |
prompt | string | Required within parent | The goal or task description for Skyvern to accomplish |
proxy_location | JSON | Optional | 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:password@proxy.example:8080"}. 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"} Default: RESIDENTIAL |
proxy_location (anyOf 1) | string | Alternative | One of: 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 |
proxy_location (anyOf 2) | Model | Alternative | Expand Update an agent — response body — proxy location city, country, is ISP, subdivision |
proxy_location (anyOf 3) | object | Alternative | Additional keys: allowed |
proxy_location (anyOf 4) | null | Alternative | |
publish_workflow | boolean | Optional | 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. Default: false |
run_with | JSON | Optional | Whether to run the task with agent or code. Null means use the default. |
run_with (anyOf 1) | string | Alternative | |
run_with (anyOf 2) | null | Alternative | |
start_fresh_browser | boolean | Optional | 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. Default: false |
title | JSON | Optional | The title for the task |
title (anyOf 1) | string | Alternative | |
title (anyOf 2) | null | Alternative | |
totp_identifier | JSON | Optional | Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to https://www.skyvern.com/docs/credentials#push-a-code for more details. |
totp_identifier (anyOf 1) | string | Alternative | |
totp_identifier (anyOf 2) | null | Alternative | |
totp_url | JSON | Optional | URL that serves TOTP/2FA/MFA codes for Skyvern to use during the workflow run. Refer to https://www.skyvern.com/docs/credentials#let-skyvern-fetch-codes-from-your-endpoint for more details. |
totp_url (anyOf 1) | string | Alternative | |
totp_url (anyOf 2) | null | Alternative | |
url | JSON | Optional | The starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL |
url (anyOf 1) | string | Alternative | |
url (anyOf 2) | null | Alternative | |
webhook_url | JSON | Optional | 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. |
webhook_url (anyOf 1) | string | Alternative | |
webhook_url (anyOf 2) | null | Alternative |
Referenced models: Update an agent — response body — proxy location city, country, is ISP, subdivision
Run a task — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
app_url | JSON | Optional | URL to the application UI where the run can be viewed |
app_url (anyOf 1) | string | Alternative | |
app_url (anyOf 2) | null | Alternative | |
browser_profile_id | JSON | Optional | ID of the browser profile used for this run |
browser_profile_id (anyOf 1) | string | Alternative | |
browser_profile_id (anyOf 2) | null | Alternative | |
browser_session_id | JSON | Optional | ID of the Skyvern persistent browser session used for this run |
browser_session_id (anyOf 1) | string | Alternative | |
browser_session_id (anyOf 2) | null | Alternative | |
created_at | string | Required within parent | Timestamp when this run was created Format: date-time |
downloaded_files | JSON | Optional | List of files downloaded during the run |
downloaded_files (anyOf 1) | array | Alternative | |
downloaded_files (anyOf 1)[] | Model | Each item | Expand Get a session — response body — recordings array item |
downloaded_files (anyOf 2) | null | Alternative | |
errors | JSON | Optional | The errors for the run |
errors (anyOf 1) | array | Alternative | |
errors (anyOf 1)[] | object | Each item | Additional keys: allowed |
errors (anyOf 2) | null | Alternative | |
failure_reason | JSON | Optional | Reason for failure if the run failed or terminated |
failure_reason (anyOf 1) | string | Alternative | |
failure_reason (anyOf 2) | null | Alternative | |
finished_at | JSON | Optional | Timestamp when this run finished |
finished_at (anyOf 1) | string | Alternative | Format: date-time |
finished_at (anyOf 2) | null | Alternative | |
max_screenshot_scrolls | JSON | Optional | The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot |
max_screenshot_scrolls (anyOf 1) | JSON | Alternative | |
max_screenshot_scrolls (anyOf 1) (anyOf 1) | integer | Alternative | |
max_screenshot_scrolls (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
max_screenshot_scrolls (anyOf 2) | null | Alternative | |
modified_at | string | Required within parent | Timestamp when this run was last modified Format: date-time |
output | JSON | Optional | Output data from the run, if any. Format/schema depends on the data extracted by the run. |
output (anyOf 1) | object | Alternative | Additional keys: allowed |
output (anyOf 2) | array | Alternative | |
output (anyOf 2)[] | JSON | Each item | |
output (anyOf 3) | string | Alternative | |
output (anyOf 4) | null | Alternative | |
queued_at | JSON | Optional | Timestamp when this run was queued |
queued_at (anyOf 1) | string | Alternative | Format: date-time |
queued_at (anyOf 2) | null | Alternative | |
recording_archived | boolean | Optional | True when the recording exists but has been archived to cold storage and is not currently accessible. Default: false |
recording_url | JSON | Optional | URL to the recording of the run |
recording_url (anyOf 1) | string | Alternative | |
recording_url (anyOf 2) | null | Alternative | |
run_id | string | Required within parent | Unique identifier for this run. Run ID starts with `tsk_` for task runs and `wr_` for workflow runs. |
run_request | JSON | Optional | The original request parameters used to start this task run |
run_request (anyOf 1) | Model | Alternative | Expand Run a task — response body — run request browser address, browser profile id, browser session id, cdp connect headers, data extraction schema, engine, error code mapping, extra http headers, file ids, include action history in verification, max screenshot scrolls, max steps, model, prompt, proxy location, publish workflow, run with, start fresh browser, title, totp identifier, totp url, url, webhook url |
run_request (anyOf 2) | null | Alternative | |
run_type | string | Required within parent | Types of a task run - task_v1, task_v2, openai_cua, anthropic_cua, ui_tars Known values: task_v1, task_v2, task_v3, openai_cua, anthropic_cua, ui_tars, yutori_navigator |
screenshot_urls | JSON | Optional | List of last n screenshot URLs in reverse chronological order - the first one the list is the latest screenshot. |
screenshot_urls (anyOf 1) | array | Alternative | |
screenshot_urls (anyOf 1)[] | string | Each item | |
screenshot_urls (anyOf 2) | null | Alternative | |
script_run | JSON | Optional | The script run result |
script_run (anyOf 1) | Model | Alternative | Expand Login Task — response body — script run ai fallback triggered, script id, script revision id |
script_run (anyOf 2) | null | Alternative | |
started_at | JSON | Optional | Timestamp when this run started execution |
started_at (anyOf 1) | string | Alternative | Format: date-time |
started_at (anyOf 2) | null | Alternative | |
status | string | Required within parent | Current status of the run Known values: created, queued, running, paused, timed_out, failed, terminated, completed, canceled |
step_count | JSON | Optional | Total number of steps executed in this run |
step_count (anyOf 1) | JSON | Alternative | |
step_count (anyOf 1) (anyOf 1) | integer | Alternative | |
step_count (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
step_count (anyOf 2) | null | Alternative |
Referenced models: Get a session — response body — recordings array item, Login Task — response body — script run ai fallback triggered, script id, script revision id, Run a task — response body — run request browser address, browser profile id, browser session id, cdp connect headers, data extraction schema, engine, error code mapping, extra http headers, file ids, include action history in verification, max screenshot scrolls, max steps, model, prompt, proxy location, publish workflow, run with, start fresh browser, title, totp identifier, totp url, url, webhook url
Run a task — response body — run request browser address, browser profile id, browser session id, cdp connect headers, data extraction schema, engine, error code mapping, extra http headers, file ids, include action history in verification, max screenshot scrolls, max steps, model, prompt, proxy location, publish workflow, run with, start fresh browser, title, totp identifier, totp url, url, webhook url
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
browser_address | JSON | Optional | The CDP address for the task. |
browser_address (anyOf 1) | string | Alternative | |
browser_address (anyOf 2) | null | Alternative | |
browser_profile_id | JSON | Optional | ID of a browser profile to reuse for this task |
browser_profile_id (anyOf 1) | string | Alternative | |
browser_profile_id (anyOf 2) | null | Alternative | |
browser_session_id | JSON | Optional | 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_session_id (anyOf 1) | string | Alternative | |
browser_session_id (anyOf 2) | null | Alternative | |
cdp_connect_headers | JSON | Optional | 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. |
cdp_connect_headers (anyOf 1) | object | Alternative | Additional keys: see wildcard field |
cdp_connect_headers (anyOf 1).* | string | Additional keys | |
cdp_connect_headers (anyOf 2) | null | Alternative | |
data_extraction_schema | JSON | Optional | The schema for data to be extracted from the webpage. If you're looking for consistent data schema being returned by the agent, it's highly recommended to use https://json-schema.org/. |
data_extraction_schema (anyOf 1) | object | Alternative | Additional keys: allowed |
data_extraction_schema (anyOf 2) | array | Alternative | |
data_extraction_schema (anyOf 2)[] | JSON | Each item | |
data_extraction_schema (anyOf 3) | string | Alternative | |
data_extraction_schema (anyOf 4) | null | Alternative | |
engine | string | Optional | The engine that powers the agent task. The default value is `skyvern-1.0`, which is good for simple tasks like filling a form, or searching for information on Google. `skyvern-2.0` remains available for existing V2 workflows and explicitly requested V2 task runs. The `openai-cua` engine uses OpenAI's CUA model. The `anthropic-cua` uses Anthropic's Claude Sonnet 3.7 model with the computer use tool. Known values: skyvern-1.0, skyvern-2.0, skyvern-3.0, openai-cua, anthropic-cua, ui-tars, yutori-navigator Default: skyvern-1.0 |
error_code_mapping | JSON | Optional | Custom mapping of error codes to error messages if Skyvern encounters an error. |
error_code_mapping (anyOf 1) | object | Alternative | Additional keys: see wildcard field |
error_code_mapping (anyOf 1).* | string | Additional keys | |
error_code_mapping (anyOf 2) | null | Alternative | |
extra_http_headers | JSON | Optional | The extra HTTP headers for the requests in browser. |
extra_http_headers (anyOf 1) | object | Alternative | Additional keys: see wildcard field |
extra_http_headers (anyOf 1).* | string | Additional keys | |
extra_http_headers (anyOf 2) | null | Alternative | |
file_ids | JSON | Optional | 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. |
file_ids (anyOf 1) | array | Alternative | Maximum items: 50 |
file_ids (anyOf 1)[] | string | Each item | |
file_ids (anyOf 2) | null | Alternative | |
include_action_history_in_verification | JSON | Optional | Whether to include action history when verifying that the task is complete Default: false |
include_action_history_in_verification (anyOf 1) | boolean | Alternative | |
include_action_history_in_verification (anyOf 2) | null | Alternative | |
max_screenshot_scrolls | JSON | Optional | The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot. |
max_screenshot_scrolls (anyOf 1) | JSON | Alternative | |
max_screenshot_scrolls (anyOf 1) (anyOf 1) | integer | Alternative | |
max_screenshot_scrolls (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
max_screenshot_scrolls (anyOf 2) | null | Alternative | |
max_steps | JSON | Optional | 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 at skyvern.com for custom pricing. |
max_steps (anyOf 1) | JSON | Alternative | |
max_steps (anyOf 1) (anyOf 1) | integer | Alternative | |
max_steps (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
max_steps (anyOf 2) | null | Alternative | |
model | JSON | Optional | Optional model configuration. |
model (anyOf 1) | object | Alternative | Additional keys: allowed |
model (anyOf 2) | null | Alternative | |
prompt | string | Required within parent | The goal or task description for Skyvern to accomplish |
proxy_location | JSON | Optional | 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:password@proxy.example:8080"}. 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"} Default: RESIDENTIAL |
proxy_location (anyOf 1) | Model | Alternative | Expand Update an agent — response body — proxy location string |
proxy_location (anyOf 2) | Model | Alternative | Expand Update an agent — response body — proxy location city, country, is ISP, subdivision |
proxy_location (anyOf 3) | object | Alternative | Additional keys: allowed |
proxy_location (anyOf 4) | null | Alternative | |
publish_workflow | boolean | Optional | 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. Default: false |
run_with | JSON | Optional | Whether to run the task with agent or code. Null means use the default. |
run_with (anyOf 1) | string | Alternative | |
run_with (anyOf 2) | null | Alternative | |
start_fresh_browser | boolean | Optional | 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. Default: false |
title | JSON | Optional | The title for the task |
title (anyOf 1) | string | Alternative | |
title (anyOf 2) | null | Alternative | |
totp_identifier | JSON | Optional | Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to https://www.skyvern.com/docs/credentials#push-a-code for more details. |
totp_identifier (anyOf 1) | string | Alternative | |
totp_identifier (anyOf 2) | null | Alternative | |
totp_url | JSON | Optional | URL that serves TOTP/2FA/MFA codes for Skyvern to use during the workflow run. Refer to https://www.skyvern.com/docs/credentials#let-skyvern-fetch-codes-from-your-endpoint for more details. |
totp_url (anyOf 1) | string | Alternative | |
totp_url (anyOf 2) | null | Alternative | |
url | JSON | Optional | The starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL |
url (anyOf 1) | string | Alternative | |
url (anyOf 2) | null | Alternative | |
webhook_url | JSON | Optional | 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. |
webhook_url (anyOf 1) | string | Alternative | |
webhook_url (anyOf 2) | null | Alternative |
Referenced models: Update an agent — response body — proxy location city, country, is ISP, subdivision, Update an agent — response body — proxy location string