> ## 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' description: >- Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings. title: X-Api-Key description: >- Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings. - 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 browser_profile_id: anyOf: - type: string - type: 'null' title: Browser Profile Id description: ID of a browser profile to reuse for this workflow run 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. 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 - 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. 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 - 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 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 browser_profile_id: anyOf: - type: string - type: 'null' title: Browser Profile Id description: ID of a browser profile to reuse for this workflow run 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. 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 ````