---
title: "Run an agent"
method: POST
path: "/v1/run/agents"
tags: ["Runs"]
---

# Run an agent

`POST /v1/run/agents`

Run an agent

## Query parameters

- `template` boolean

## Headers

- `x-api-key` string, nullable
- `x-max-steps-override` integer, nullable
- `x-user-agent` string, nullable

## Request body

- WorkflowRunRequestInput
  - `agent_id` string, required — ID of the agent to run. Starts with `wpid_`. `workflow_id` is accepted as an alias.
  - `parameters` object, nullable — Parameters to pass to the workflow
  - `title` string, nullable — The title for this workflow run
  - `proxy_location` union — 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.com: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"}
    - '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'
    - GeoTarget — Granular proxy geo-targeting request with country, optional subdivision, and optional city.
      - `country` string, required — ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE')
      - `subdivision` string, nullable — ISO 3166-2 subdivision code without country prefix (e.g., 'CA' for California, 'NY' for New York)
      - `city` string, nullable — City name in English from GeoNames (e.g., 'New York', 'Los Angeles', 'London')
    - object
  - `webhook_url` string, 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_url` string, 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_identifier` string, 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_id` string, nullable — ID of a Skyvern browser session to reuse, having it continue from the current screen state
  - `browser_profile_id` string, nullable — ID of a browser profile to reuse for this workflow run
  - `start_fresh_browser` boolean — 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_scrolls` integer, 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_minutes` integer, 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_headers` object, nullable — The extra HTTP headers for the requests in browser.
  - `cdp_connect_headers` object, 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_address` string, nullable — The CDP address for the workflow run.
  - `ai_fallback` boolean, nullable — Whether to fallback to AI if the workflow run fails.
  - `run_with` string, nullable — Whether to run the workflow with agent or code. Null inherits from the workflow setting.
  - `run_metadata` object, nullable — String key/value metadata to attach to this workflow run for analytics tag filtering.

## Response `200`

Successfully ran agent

- WorkflowRunResponse
  - `run_id` string, 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
  - `output` union — Output data from the run, if any. Format/schema depends on the data extracted by the run.
    - object
    - unknown[]
      - unknown
    - string
  - `downloaded_files` FileInfo[], nullable — List of files downloaded during the run
    - `url` string, required — URL to access the file
    - `checksum` string, nullable — SHA-256 checksum of the file
    - `filename` string, nullable — Original filename
    - `file_size` integer, nullable — Size of the file in bytes
    - `modified_at` string, date-time, nullable — Modified time of the file
    - `artifact_id` string, nullable — Artifact row id for refresh-on-read
  - `recording_url` string, nullable — URL to the recording of the run
  - `recording_archived` boolean — True when the recording exists but has been archived to cold storage and is not currently accessible.
  - `screenshot_urls` string[], nullable — List of last n screenshot URLs in reverse chronological order - the first one the list is the latest screenshot.
  - `failure_reason` string, nullable — Reason for failure if the run failed or terminated
  - `created_at` string, date-time, required — Timestamp when this run was created
  - `modified_at` string, date-time, required — Timestamp when this run was last modified
  - `queued_at` string, date-time, nullable — Timestamp when this run was queued
  - `started_at` string, date-time, nullable — Timestamp when this run started execution
  - `finished_at` string, date-time, nullable — Timestamp when this run finished
  - `app_url` string, nullable — URL to the application UI where the run can be viewed
  - `browser_session_id` string, nullable — ID of the Skyvern persistent browser session used for this run
  - `browser_profile_id` string, nullable — ID of the browser profile used for this run
  - `max_screenshot_scrolls` integer, nullable — The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot
  - `script_run` ScriptRunResponse
    - `ai_fallback_triggered` boolean
    - `script_id` string, nullable
    - `script_revision_id` string, nullable
  - `errors` object[], nullable — The errors for the run
  - `step_count` integer, nullable — Total number of steps executed in this run
  - `run_type` 'workflow_run', required — Type of run - always workflow_run for workflow runs
  - `run_with` string — Whether the workflow run was executed with agent or code
  - `ai_fallback` boolean, nullable — Whether to fallback to AI if code run fails.
  - `script_id` string, 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
  - `run_request` WorkflowRunRequestOutput
    - `workflow_id` string, required — ID of the agent to run. Starts with `wpid_`. `workflow_id` is accepted as an alias.
    - `parameters` object, nullable — Parameters to pass to the workflow
    - `title` string, nullable — The title for this workflow run
    - `proxy_location` union — 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.com: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"}
      - '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'
      - GeoTarget — Granular proxy geo-targeting request with country, optional subdivision, and optional city.
        - `country` string, required — ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE')
        - `subdivision` string, nullable — ISO 3166-2 subdivision code without country prefix (e.g., 'CA' for California, 'NY' for New York)
        - `city` string, nullable — City name in English from GeoNames (e.g., 'New York', 'Los Angeles', 'London')
      - object
    - `webhook_url` string, 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_url` string, 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_identifier` string, 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_id` string, nullable — ID of a Skyvern browser session to reuse, having it continue from the current screen state
    - `browser_profile_id` string, nullable — ID of a browser profile to reuse for this workflow run
    - `start_fresh_browser` boolean — 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_scrolls` integer, 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_minutes` integer, 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_headers` object, nullable — The extra HTTP headers for the requests in browser.
    - `cdp_connect_headers` object, 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_address` string, nullable — The CDP address for the workflow run.
    - `ai_fallback` boolean, nullable — Whether to fallback to AI if the workflow run fails.
    - `run_with` string, nullable — Whether to run the workflow with agent or code. Null inherits from the workflow setting.
    - `run_metadata` object, nullable — String key/value metadata to attach to this workflow run for analytics tag filtering.

## Other responses

- `400` — Invalid agent run request
- `422` — Validation Error

---

[API](https://skmtc.net/skyvern-ai/apis/skyvern-api-2.md) · [All operations](https://skmtc.net/skyvern-ai/apis/skyvern-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/skyvern-ai/skyvern-api-2/versions/29562c6e0364/schema)