--- title: "Get run info by id" method: GET path: "/v1/runs/{run_id}" tags: ["Runs"] --- # Get run info by id `GET /v1/runs/{run_id}` Get run information (task run, workflow run) ## Path parameters - `run_id` string, required — The id of the task run or the workflow run. ## Headers - `x-api-key` string, nullable — Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings. ## Response `200` Successfully got run - union - TaskRunResponse - `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` 'task_v1' | 'task_v2' | 'openai_cua' | 'anthropic_cua' | 'ui_tars' | 'yutori_navigator', required — Types of a task run - task_v1, task_v2, openai_cua, anthropic_cua, ui_tars - `run_request` TaskRunRequestOutput - `prompt` string, required — The goal or task description for Skyvern to accomplish - `url` string, nullable — The starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL - `engine` 'skyvern-1.0' | 'skyvern-2.0' | 'openai-cua' | 'anthropic-cua' | 'ui-tars' | 'yutori-navigator' - `title` string, nullable — The title for the task - `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 - `data_extraction_schema` union — 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/. - object - unknown[] - unknown - string - `error_code_mapping` object, nullable — Custom mapping of error codes to error messages if Skyvern encounters an error. - `max_steps` integer, nullable — Maximum number of steps the task can take. Task will fail if it exceeds this number. Cautions: you are charged per step so please set this number to a reasonable value. Contact sales@skyvern.com for custom pricing. - `webhook_url` string, nullable — After a run is finished, send an update to this URL. Refer to https://www.skyvern.com/docs/running-tasks/webhooks-faq for more details. - `totp_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. - `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. - `browser_session_id` string, nullable — Run the task or workflow in the specific Skyvern browser session. Having a browser session can persist the real-time state of the browser, so that the next run can continue from where the previous run left off. - `browser_profile_id` string, nullable — ID of a browser profile to reuse for this task - `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. - `model` object, nullable — Optional model configuration. - `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. - `publish_workflow` boolean — Deprecated. Whether to publish a `skyvern-2.0` task as a reusable workflow. For backwards compatibility, this routes the request through the legacy `skyvern-2.0` publish path. Prefer creating reusable workflows through the workflow APIs. - `include_action_history_in_verification` boolean, nullable — Whether to include action history when verifying that the task is complete - `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. - `browser_address` string, nullable — The CDP address for the task. - `run_with` string, nullable — Whether to run the task with agent or code. Null means use the default. - 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 - `404` — Run not found - `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)