> ## Documentation Index > Fetch the complete documentation index at: https://skyvern.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Run an agent > Run an agent ## OpenAPI ````yaml /api-reference/openapi.json post /v1/run/agents openapi: 3.1.0 info: title: Skyvern API description: API for Skyvern version: 1.0.0 servers: - url: https://api.skyvern.com x-fern-server-name: Cloud - url: https://api-staging.skyvern.com x-fern-server-name: Staging - url: http://localhost:8000 x-fern-server-name: Local security: [] paths: /v1/run/agents: post: tags: - Runs summary: Run an agent description: Run an agent operationId: run_workflow_v1_run_agents_post parameters: - name: template in: query required: false schema: type: boolean default: false title: Template - name: x-api-key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key - name: x-max-steps-override in: header required: false schema: anyOf: - type: integer - type: 'null' title: X-Max-Steps-Override - name: x-user-agent in: header required: false schema: anyOf: - type: string - type: 'null' title: X-User-Agent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkflowRunRequest-Input' responses: '200': description: Successfully ran agent content: application/json: schema: $ref: '#/components/schemas/WorkflowRunResponse' '400': description: Invalid agent run request '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: WorkflowRunRequest-Input: properties: agent_id: type: string title: Agent Id description: >- ID of the agent to run. Starts with `wpid_`. `workflow_id` is accepted as an alias. examples: - wpid_123 parameters: anyOf: - additionalProperties: true type: object - type: 'null' title: Parameters description: Parameters to pass to the workflow title: anyOf: - type: string - type: 'null' title: Title description: The title for this workflow run proxy_location: anyOf: - $ref: '#/components/schemas/ProxyLocation' - $ref: '#/components/schemas/GeoTarget' - additionalProperties: true type: object - type: 'null' title: Proxy Location description: >- 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"} default: RESIDENTIAL webhook_url: anyOf: - type: string - type: 'null' title: Webhook Url description: >- 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: anyOf: - type: string - type: 'null' title: Totp Url description: > 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. examples: - https://my-totp-service.com/totp totp_identifier: anyOf: - type: string - type: 'null' title: Totp Identifier description: > 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. examples: - john.doe@example.com - '4155555555' - user_123 browser_session_id: anyOf: - type: string - type: 'null' title: Browser Session Id description: >- ID of a Skyvern browser session to reuse, having it continue from the current screen state reuse_browser_session: anyOf: - type: boolean - type: 'null' title: Reuse Browser Session description: >- 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_id: anyOf: - type: string - type: 'null' title: Browser Profile Id description: ID of a browser profile to reuse for this workflow run start_fresh_browser: type: boolean title: Start Fresh Browser description: >- 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 max_screenshot_scrolls: anyOf: - type: integer - type: 'null' title: Max Screenshot Scrolls description: >- 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: anyOf: - type: integer maximum: 480 minimum: 1 - type: 'null' title: Max Elapsed Time Minutes description: >- 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: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Extra Http Headers description: The extra HTTP headers for the requests in browser. cdp_connect_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Cdp Connect Headers description: >- 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: anyOf: - type: string - type: 'null' title: Browser Address description: The CDP address for the workflow run. examples: - http://127.0.0.1:9222 - ws://127.0.0.1:9222/devtools/browser/1234567890 ai_fallback: anyOf: - type: boolean - type: 'null' title: Ai Fallback description: Whether to fallback to AI if the workflow run fails. run_with: anyOf: - type: string - type: 'null' title: Run With description: >- Whether to run the workflow with agent or code. Null inherits from the workflow setting. examples: - agent - code run_metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Run Metadata description: >- String key/value metadata to attach to this workflow run for analytics tag filtering. file_ids: anyOf: - items: type: string type: array maxItems: 50 - type: 'null' title: File Ids description: > 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. examples: - - file_123456789 type: object required: - agent_id title: WorkflowRunRequest WorkflowRunResponse: properties: run_id: type: string title: Run Id description: >- Unique identifier for this run. Run ID starts with `tsk_` for task runs and `wr_` for workflow runs. examples: - tsk_123 - tsk_v2_123 - wr_123 status: $ref: '#/components/schemas/RunStatus' description: Current status of the run examples: - created - queued - running - paused - timed_out - failed - terminated - completed - canceled output: anyOf: - additionalProperties: true type: object - items: {} type: array - type: string - type: 'null' title: Output description: >- Output data from the run, if any. Format/schema depends on the data extracted by the run. downloaded_files: anyOf: - items: $ref: '#/components/schemas/FileInfo' type: array - type: 'null' title: Downloaded Files description: List of files downloaded during the run recording_url: anyOf: - type: string - type: 'null' title: Recording Url description: URL to the recording of the run recording_archived: type: boolean title: Recording Archived description: >- True when the recording exists but has been archived to cold storage and is not currently accessible. default: false screenshot_urls: anyOf: - items: type: string type: array - type: 'null' title: Screenshot Urls description: >- List of last n screenshot URLs in reverse chronological order - the first one the list is the latest screenshot. failure_reason: anyOf: - type: string - type: 'null' title: Failure Reason description: Reason for failure if the run failed or terminated created_at: type: string format: date-time title: Created At description: Timestamp when this run was created examples: - '2025-01-01T00:00:00Z' modified_at: type: string format: date-time title: Modified At description: Timestamp when this run was last modified examples: - '2025-01-01T00:05:00Z' queued_at: anyOf: - type: string format: date-time - type: 'null' title: Queued At description: Timestamp when this run was queued started_at: anyOf: - type: string format: date-time - type: 'null' title: Started At description: Timestamp when this run started execution finished_at: anyOf: - type: string format: date-time - type: 'null' title: Finished At description: Timestamp when this run finished app_url: anyOf: - type: string - type: 'null' title: App Url description: URL to the application UI where the run can be viewed examples: - https://app.skyvern.com/tasks/tsk_123 - https://app.skyvern.com/workflows/wpid_123/wr_123 browser_session_id: anyOf: - type: string - type: 'null' title: Browser Session Id description: ID of the Skyvern persistent browser session used for this run examples: - pbs_123 browser_profile_id: anyOf: - type: string - type: 'null' title: Browser Profile Id description: ID of the browser profile used for this run examples: - bp_123 max_screenshot_scrolls: anyOf: - type: integer - type: 'null' title: Max Screenshot Scrolls description: >- The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot script_run: anyOf: - $ref: '#/components/schemas/ScriptRunResponse' - type: 'null' description: The script run result errors: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Errors description: The errors for the run step_count: anyOf: - type: integer - type: 'null' title: Step Count description: Total number of steps executed in this run run_type: type: string const: workflow_run title: Run Type description: Type of run - always workflow_run for workflow runs run_with: type: string title: Run With description: Whether the workflow run was executed with agent or code default: agent examples: - agent - code ai_fallback: anyOf: - type: boolean - type: 'null' title: Ai Fallback description: Whether to fallback to AI if code run fails. script_id: anyOf: - type: string - type: 'null' title: Script Id description: ID of the cached script used for this workflow run, if any. browser_seed_source: anyOf: - $ref: '#/components/schemas/BrowserSeedSource' - type: 'null' description: >- Which layer of the seed-precedence chain seeded this run's browser (provenance). examples: - credential - own_memory - fresh run_request: anyOf: - $ref: '#/components/schemas/WorkflowRunRequest-Output' - type: 'null' description: The original request parameters used to start this workflow run type: object required: - run_id - status - created_at - modified_at - run_type title: WorkflowRunResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ProxyLocation: type: string enum: - 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 title: ProxyLocation GeoTarget: properties: country: type: string maxLength: 2 minLength: 2 title: Country description: ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE') examples: - US - GB - DE - FR subdivision: anyOf: - type: string maxLength: 10 - type: 'null' title: Subdivision description: >- ISO 3166-2 subdivision code without country prefix (e.g., 'CA' for California, 'NY' for New York) examples: - CA - NY - TX - ENG city: anyOf: - type: string maxLength: 100 - type: 'null' title: City description: >- City name in English from GeoNames (e.g., 'New York', 'Los Angeles', 'London') examples: - New York - Los Angeles - London - Berlin type: object required: - country title: GeoTarget description: >- Granular proxy geo-targeting request with country, optional subdivision, and optional city. RunStatus: type: string enum: - created - queued - running - paused - timed_out - failed - terminated - completed - canceled title: RunStatus FileInfo: properties: url: type: string title: Url description: URL to access the file checksum: anyOf: - type: string - type: 'null' title: Checksum description: SHA-256 checksum of the file filename: anyOf: - type: string - type: 'null' title: Filename description: Original filename file_size: anyOf: - type: integer - type: 'null' title: File Size description: Size of the file in bytes modified_at: anyOf: - type: string format: date-time - type: 'null' title: Modified At description: Modified time of the file artifact_id: anyOf: - type: string - type: 'null' title: Artifact Id description: Artifact row id for refresh-on-read type: object required: - url title: FileInfo description: Information about a downloaded file, including URL and checksum. ScriptRunResponse: properties: ai_fallback_triggered: type: boolean title: Ai Fallback Triggered default: false script_id: anyOf: - type: string - type: 'null' title: Script Id script_revision_id: anyOf: - type: string - type: 'null' title: Script Revision Id type: object title: ScriptRunResponse BrowserSeedSource: type: string enum: - override - picked - own_memory - credential - fresh - degraded_fresh title: BrowserSeedSource description: >- 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 WorkflowRunRequest-Output: properties: workflow_id: type: string title: Workflow Id description: >- ID of the agent to run. Starts with `wpid_`. `workflow_id` is accepted as an alias. examples: - wpid_123 parameters: anyOf: - additionalProperties: true type: object - type: 'null' title: Parameters description: Parameters to pass to the workflow title: anyOf: - type: string - type: 'null' title: Title description: The title for this workflow run proxy_location: anyOf: - $ref: '#/components/schemas/ProxyLocation' - $ref: '#/components/schemas/GeoTarget' - additionalProperties: true type: object - type: 'null' title: Proxy Location description: >- 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"} default: RESIDENTIAL webhook_url: anyOf: - type: string - type: 'null' title: Webhook Url description: >- 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: anyOf: - type: string - type: 'null' title: Totp Url description: > 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. examples: - https://my-totp-service.com/totp totp_identifier: anyOf: - type: string - type: 'null' title: Totp Identifier description: > 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. examples: - john.doe@example.com - '4155555555' - user_123 browser_session_id: anyOf: - type: string - type: 'null' title: Browser Session Id description: >- ID of a Skyvern browser session to reuse, having it continue from the current screen state reuse_browser_session: anyOf: - type: boolean - type: 'null' title: Reuse Browser Session description: >- 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_id: anyOf: - type: string - type: 'null' title: Browser Profile Id description: ID of a browser profile to reuse for this workflow run start_fresh_browser: type: boolean title: Start Fresh Browser description: >- 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 max_screenshot_scrolls: anyOf: - type: integer - type: 'null' title: Max Screenshot Scrolls description: >- 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: anyOf: - type: integer maximum: 480 minimum: 1 - type: 'null' title: Max Elapsed Time Minutes description: >- 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: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Extra Http Headers description: The extra HTTP headers for the requests in browser. cdp_connect_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Cdp Connect Headers description: >- 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: anyOf: - type: string - type: 'null' title: Browser Address description: The CDP address for the workflow run. examples: - http://127.0.0.1:9222 - ws://127.0.0.1:9222/devtools/browser/1234567890 ai_fallback: anyOf: - type: boolean - type: 'null' title: Ai Fallback description: Whether to fallback to AI if the workflow run fails. run_with: anyOf: - type: string - type: 'null' title: Run With description: >- Whether to run the workflow with agent or code. Null inherits from the workflow setting. examples: - agent - code run_metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Run Metadata description: >- String key/value metadata to attach to this workflow run for analytics tag filtering. file_ids: anyOf: - items: type: string type: array maxItems: 50 - type: 'null' title: File Ids description: > 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. examples: - - file_123456789 type: object required: - workflow_id title: WorkflowRunRequest ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ````