> ## 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. # Get all runs > List workflow runs across all workflows for the current organization. Results are paginated and can be filtered by **status**, **search_key**, and **error_code**. All filters are combined with **AND** logic — a run must match every supplied filter to be returned. ### search_key A case-insensitive substring search that matches against **any** of the following fields: | Searched field | Description | |---|---| | `workflow_run_id` | The unique run identifier (e.g. `wr_123…`) | | `workflow_permanent_id` | The permanent ID of the workflow that ran (e.g. `wpid_123…`) | | Workflow **title** | The title of the workflow that ran | | Parameter **key** | The `key` of any workflow parameter definition associated with the run | | Parameter **description** | The `description` of any workflow parameter definition | | Run parameter **value** | The actual value supplied for any parameter when the run was created | | `extra_http_headers` | Extra HTTP headers attached to the run (searched as raw JSON text) | | `webhook_callback_url` | The webhook URL the run posts its result to | Soft-deleted parameter definitions are excluded from key/description matching. A run is returned if **any** of the fields above contain the search term. A **complete** identifier also matches the run that used it, by exact equality: | Identifier | Description | |---|---| | `browser_profile_id` | The browser profile the run used (e.g. `bp_123…`) | | `browser_session_id` | The browser session the run used (e.g. `pbs_123…`) | | **Credential id** | A credential the run used (e.g. `cred_123…`) | | `workflow_run_id` | The run itself (e.g. `wr_123…`) | | **Task id** | The workflow run the task ran in, when that run is top-level (e.g. `tsk_123…`) | A complete browser profile, browser session, workflow run or task id is matched against those identifiers only, not the text fields above. A credential id matches a run when it is the run's sequential credential, the credential the run selected from a pool or fell back to, or the credential bound by a credential parameter on the run's workflow version when the run was created and the run recorded no selection for that parameter. Other pool and fallback members the run did not use do not match. ### Default search window A `search_key` other than a complete browser profile, browser session, workflow run or task id is matched only against runs created in the **30 days before `created_at_end`** (or before now) unless the request supplies `created_at_start`. This includes complete credential ids. Supply `created_at_start` (and optionally `created_at_end`) to search a different range. Explicit bounds apply to every search, complete ids included. Listings without `search_key` are not windowed. To fetch one run by its id, use `GET /v1/runs/{run_id}`. ### created_at_start / created_at_end Optional ISO 8601 bounds on the run's creation time: `created_at_start` is inclusive and `created_at_end` is exclusive. A timestamp without an offset is read as UTC. ### error_code An **exact-match** filter against the `error_code` field inside each task's `errors` JSON array. A run matches if **any** of its tasks contains an error object with a matching `error_code` value. Error codes are user-defined strings set during workflow execution (e.g. `INVALID_CREDENTIALS`, `LOGIN_FAILED`, `CAPTCHA_DETECTED`). ### Combining filters All query parameters use AND logic: - `?status=failed` — only failed runs - `?status=failed&error_code=LOGIN_FAILED` — failed runs **and** have a LOGIN_FAILED error - `?status=failed&error_code=LOGIN_FAILED&search_key=prod_credential` — all three conditions must match (searched over the last 30 days) - `?search_key=prod_credential&created_at_start=2026-01-01T00:00:00Z&created_at_end=2026-02-01T00:00:00Z` — search one explicit month ## OpenAPI ````yaml /api-reference/openapi.json get /v1/agents/runs 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 security: [] paths: /v1/agents/runs: get: tags: - Runs summary: Get all runs description: >- List workflow runs across all workflows for the current organization. Results are paginated and can be filtered by **status**, **search_key**, and **error_code**. All filters are combined with **AND** logic — a run must match every supplied filter to be returned. ### search_key A case-insensitive substring search that matches against **any** of the following fields: | Searched field | Description | |---|---| | `workflow_run_id` | The unique run identifier (e.g. `wr_123…`) | | `workflow_permanent_id` | The permanent ID of the workflow that ran (e.g. `wpid_123…`) | | Workflow **title** | The title of the workflow that ran | | Parameter **key** | The `key` of any workflow parameter definition associated with the run | | Parameter **description** | The `description` of any workflow parameter definition | | Run parameter **value** | The actual value supplied for any parameter when the run was created | | `extra_http_headers` | Extra HTTP headers attached to the run (searched as raw JSON text) | | `webhook_callback_url` | The webhook URL the run posts its result to | Soft-deleted parameter definitions are excluded from key/description matching. A run is returned if **any** of the fields above contain the search term. A **complete** identifier also matches the run that used it, by exact equality: | Identifier | Description | |---|---| | `browser_profile_id` | The browser profile the run used (e.g. `bp_123…`) | | `browser_session_id` | The browser session the run used (e.g. `pbs_123…`) | | **Credential id** | A credential the run used (e.g. `cred_123…`) | | `workflow_run_id` | The run itself (e.g. `wr_123…`) | | **Task id** | The workflow run the task ran in, when that run is top-level (e.g. `tsk_123…`) | A complete browser profile, browser session, workflow run or task id is matched against those identifiers only, not the text fields above. A credential id matches a run when it is the run's sequential credential, the credential the run selected from a pool or fell back to, or the credential bound by a credential parameter on the run's workflow version when the run was created and the run recorded no selection for that parameter. Other pool and fallback members the run did not use do not match. ### Default search window A `search_key` other than a complete browser profile, browser session, workflow run or task id is matched only against runs created in the **30 days before `created_at_end`** (or before now) unless the request supplies `created_at_start`. This includes complete credential ids. Supply `created_at_start` (and optionally `created_at_end`) to search a different range. Explicit bounds apply to every search, complete ids included. Listings without `search_key` are not windowed. To fetch one run by its id, use `GET /v1/runs/{run_id}`. ### created_at_start / created_at_end Optional ISO 8601 bounds on the run's creation time: `created_at_start` is inclusive and `created_at_end` is exclusive. A timestamp without an offset is read as UTC. ### error_code An **exact-match** filter against the `error_code` field inside each task's `errors` JSON array. A run matches if **any** of its tasks contains an error object with a matching `error_code` value. Error codes are user-defined strings set during workflow execution (e.g. `INVALID_CREDENTIALS`, `LOGIN_FAILED`, `CAPTCHA_DETECTED`). ### Combining filters All query parameters use AND logic: - `?status=failed` — only failed runs - `?status=failed&error_code=LOGIN_FAILED` — failed runs **and** have a LOGIN_FAILED error - `?status=failed&error_code=LOGIN_FAILED&search_key=prod_credential` — all three conditions must match (searched over the last 30 days) - `?search_key=prod_credential&created_at_start=2026-01-01T00:00:00Z&created_at_end=2026-02-01T00:00:00Z` — search one explicit month operationId: get_workflow_runs_v1_workflows_runs_get parameters: - name: page in: query required: false schema: type: integer maximum: 1000000 minimum: 1 description: Page number for pagination. default: 1 title: Page description: Page number for pagination. - name: page_size in: query required: false schema: type: integer maximum: 1000 minimum: 1 description: Number of runs to return per page. default: 10 title: Page Size description: Number of runs to return per page. - name: status in: query required: false schema: anyOf: - type: array items: $ref: '#/components/schemas/WorkflowRunStatus' - type: 'null' description: Filter by one or more run statuses. title: Status description: Filter by one or more run statuses. - name: search_key in: query required: false schema: anyOf: - type: string maxLength: 500 - type: 'null' description: >- Case-insensitive substring search across: workflow run ID, parameter key, parameter description, run parameter value, extra HTTP headers and webhook callback URL. A run is returned if any of these fields match. Soft-deleted parameter definitions are excluded from key/description matching. A complete browser profile ID, browser session ID or credential ID matches the run that used it exactly (no substring match). A complete workflow run ID matches that run. A complete task ID matches the workflow run the task ran in, when this list includes that run, or the standalone task itself where standalone tasks are listed. A complete browser profile, browser session, workflow run or task ID is matched against those identifiers only, not the text fields. A credential ID matches when it is the run's sequential credential, the credential the run selected from a pool or fell back to, or the credential bound by a credential parameter on the run's workflow version when the run was created and the run recorded no selection for it. The workflow title and workflow permanent ID are matched as well. Without created_at_start, a search other than a complete browser profile, browser session, workflow run or task ID covers only runs created in the 30 days before created_at_end (or before now). examples: - login_url - wr_abc123 - bp_123456789 - cred_123456789 title: Search Key description: >- Case-insensitive substring search across: workflow run ID, parameter key, parameter description, run parameter value, extra HTTP headers and webhook callback URL. A run is returned if any of these fields match. Soft-deleted parameter definitions are excluded from key/description matching. A complete browser profile ID, browser session ID or credential ID matches the run that used it exactly (no substring match). A complete workflow run ID matches that run. A complete task ID matches the workflow run the task ran in, when this list includes that run, or the standalone task itself where standalone tasks are listed. A complete browser profile, browser session, workflow run or task ID is matched against those identifiers only, not the text fields. A credential ID matches when it is the run's sequential credential, the credential the run selected from a pool or fell back to, or the credential bound by a credential parameter on the run's workflow version when the run was created and the run recorded no selection for it. The workflow title and workflow permanent ID are matched as well. Without created_at_start, a search other than a complete browser profile, browser session, workflow run or task ID covers only runs created in the 30 days before created_at_end (or before now). - name: error_code in: query required: false schema: anyOf: - type: string maxLength: 500 - type: 'null' description: >- Exact-match filter on the error_code field inside each task's errors JSON array. A run matches if any of its tasks contains an error with a matching error_code. Error codes are user-defined strings set during workflow execution. examples: - INVALID_CREDENTIALS - LOGIN_FAILED - CAPTCHA_DETECTED title: Error Code description: >- Exact-match filter on the error_code field inside each task's errors JSON array. A run matches if any of its tasks contains an error with a matching error_code. Error codes are user-defined strings set during workflow execution. - name: created_at_start in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: >- Only include runs created at or after this timestamp (ISO 8601; a value without an offset is read as UTC). Supplying it replaces the 30-day default window of a free-text search_key. examples: - '2026-01-01T00:00:00Z' title: Created At Start description: >- Only include runs created at or after this timestamp (ISO 8601; a value without an offset is read as UTC). Supplying it replaces the 30-day default window of a free-text search_key. - name: created_at_end in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: >- Only include runs created strictly before this timestamp (ISO 8601; a value without an offset is read as UTC). Without created_at_start, a free-text search_key covers the 30 days before this timestamp. examples: - '2026-02-01T00:00:00Z' title: Created At End description: >- Only include runs created strictly before this timestamp (ISO 8601; a value without an offset is read as UTC). Without created_at_start, a free-text search_key covers the 30 days before this timestamp. responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/WorkflowRun' title: Response Get Workflow Runs V1 Workflows Runs Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - ApiKeyAuth: [] components: schemas: WorkflowRunStatus: type: string enum: - created - queued - running - failed - terminated - canceled - timed_out - completed - paused title: WorkflowRunStatus WorkflowRun: properties: workflow_run_id: type: string title: Workflow Run Id workflow_id: type: string title: Workflow Id workflow_permanent_id: type: string title: Workflow Permanent Id organization_id: type: string title: Organization Id browser_session_id: anyOf: - type: string - type: 'null' title: Browser Session Id browser_profile_id: anyOf: - type: string - type: 'null' title: Browser Profile Id browser_seed_source: anyOf: - $ref: '#/components/schemas/BrowserSeedSource' - type: 'null' browser_sink_profile_id: anyOf: - type: string - type: 'null' title: Browser Sink Profile Id start_fresh_browser: anyOf: - type: boolean - type: 'null' title: Start Fresh Browser reuse_browser_session: anyOf: - type: boolean - type: 'null' title: Reuse Browser Session debug_session_id: anyOf: - type: string - type: 'null' title: Debug Session Id status: $ref: '#/components/schemas/WorkflowRunStatus' attempt: type: integer title: Attempt description: One-based number of the current workflow run attempt default: 1 retry_pending: type: boolean title: Retry Pending description: Whether another attempt is scheduled for this workflow run default: false next_attempt_at: anyOf: - type: string format: date-time - type: 'null' title: Next Attempt At description: Timestamp when the next workflow run attempt is scheduled attempts: items: $ref: '#/components/schemas/WorkflowRunAttempt' type: array title: Attempts description: Attempts recorded for this workflow run extra_http_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Extra Http Headers cdp_connect_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Cdp Connect Headers proxy_location: anyOf: - $ref: '#/components/schemas/ProxyLocation' - $ref: '#/components/schemas/GeoTarget' - additionalProperties: true type: object - type: 'null' title: Proxy Location webhook_callback_url: anyOf: - type: string - type: 'null' title: Webhook Callback Url webhook_failure_reason: anyOf: - type: string - type: 'null' title: Webhook Failure Reason totp_verification_url: anyOf: - type: string - type: 'null' title: Totp Verification Url totp_identifier: anyOf: - type: string - type: 'null' title: Totp Identifier failure_reason: anyOf: - type: string - type: 'null' title: Failure Reason failure_category: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Failure Category retried_from_workflow_run_id: anyOf: - type: string - type: 'null' title: Retried From Workflow Run Id fallback_attempt: anyOf: - type: integer - type: 'null' title: Fallback Attempt parent_workflow_run_id: anyOf: - type: string - type: 'null' title: Parent Workflow Run Id workflow_title: anyOf: - type: string - type: 'null' title: Workflow Title max_screenshot_scrolls: anyOf: - type: integer - type: 'null' title: Max Screenshot Scrolls max_elapsed_time_minutes: anyOf: - type: integer - type: 'null' title: Max Elapsed Time Minutes browser_address: anyOf: - type: string - type: 'null' title: Browser Address run_with: anyOf: - type: string - type: 'null' title: Run With browser_type: anyOf: - type: string - type: 'null' title: Browser Type browser_settings: anyOf: - $ref: '#/components/schemas/BrowserSettings' - type: 'null' description: >- Browser settings copied from the workflow version when the run was created browser_settings_receipt: anyOf: - $ref: '#/components/schemas/BrowserSettingsReceipt' - type: 'null' script_run: anyOf: - $ref: '#/components/schemas/ScriptRunResponse' - type: 'null' job_id: anyOf: - type: string - type: 'null' title: Job Id depends_on_workflow_run_id: anyOf: - type: string - type: 'null' title: Depends On Workflow Run Id sequential_key: anyOf: - type: string - type: 'null' title: Sequential Key sequential_credential_id: anyOf: - type: string - type: 'null' title: Sequential Credential Id ai_fallback: anyOf: - type: boolean - type: 'null' title: Ai Fallback code_gen: anyOf: - type: boolean - type: 'null' title: Code Gen trigger_type: anyOf: - $ref: '#/components/schemas/WorkflowRunTriggerType' - type: 'null' workflow_schedule_id: anyOf: - type: string - type: 'null' title: Workflow Schedule Id ignore_inherited_workflow_system_prompt: type: boolean title: Ignore Inherited Workflow System Prompt default: false copilot_session_id: anyOf: - type: string - type: 'null' title: Copilot Session Id created_by: anyOf: - type: string - type: 'null' title: Created By description: ID of the user who started the run credits_used: type: integer title: Credits Used default: 0 cached_credits_used: type: integer title: Cached Credits Used default: 0 queued_at: anyOf: - type: string format: date-time - type: 'null' title: Queued At started_at: anyOf: - type: string format: date-time - type: 'null' title: Started At finished_at: anyOf: - type: string format: date-time - type: 'null' title: Finished At created_at: type: string format: date-time title: Created At modified_at: type: string format: date-time title: Modified At type: object required: - workflow_run_id - workflow_id - workflow_permanent_id - organization_id - status - created_at - modified_at title: WorkflowRun HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError 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 at run setup, before any browser creation, for all run types (C-semantics). A serialized Save & Reuse run re-resolves once more after the sequential wait, so a profile an earlier run in its lane saved while it was queued becomes own_memory rather than a stale pick. - 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 WorkflowRunAttempt: properties: attempt_number: type: integer title: Attempt Number description: One-based number of this workflow run attempt status: $ref: '#/components/schemas/RunStatus' description: Status of this workflow run attempt failure_reason: anyOf: - type: string - type: 'null' title: Failure Reason description: Reason for failure, if the attempt failed error_codes: items: type: string type: array title: Error Codes description: Error codes reported by this attempt started_at: anyOf: - type: string format: date-time - type: 'null' title: Started At description: Timestamp when this attempt started finished_at: anyOf: - type: string format: date-time - type: 'null' title: Finished At description: Timestamp when this attempt finished retry_decision: anyOf: - type: string - type: 'null' title: Retry Decision description: Retry decision recorded for this attempt decision_reason: anyOf: - type: string - type: 'null' title: Decision Reason description: Reason recorded for the retry decision next_attempt_at: anyOf: - type: string format: date-time - type: 'null' title: Next Attempt At description: Timestamp when the next attempt is scheduled webhook_sent_at: anyOf: - type: string format: date-time - type: 'null' title: Webhook Sent At description: Timestamp when the webhook for this attempt was sent type: object required: - attempt_number - status title: WorkflowRunAttempt 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 isISP: type: boolean title: Isisp description: Whether this geo target is marked as an ISP proxy location. default: false type: object required: - country title: GeoTarget description: >- Granular proxy geo-targeting request with country, optional subdivision, and optional city. BrowserSettings: properties: timezone_id: anyOf: - type: string - type: 'null' title: Timezone Id description: >- IANA timezone the browser reports to pages, for example `America/New_York`. Applied when a browser is created and takes precedence over any timezone implied by the proxy location. Offsets such as `+03:00` are rejected. Omit or set to null to keep the default behavior. examples: - America/New_York type: object title: BrowserSettings BrowserSettingsReceipt: properties: requested_timezone_id: type: string title: Requested Timezone Id description: The timezone that was requested. actual_timezone_id: anyOf: - type: string - type: 'null' title: Actual Timezone Id description: >- The timezone the browser reported when measured, or null when it could not be measured. source: $ref: '#/components/schemas/BrowserSettingsSource' description: Where the requested setting came from. status: $ref: '#/components/schemas/BrowserSettingsStatus' description: >- `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. warning: anyOf: - type: string - type: 'null' title: Warning type: object required: - requested_timezone_id - source - status title: BrowserSettingsReceipt 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 WorkflowRunTriggerType: type: string enum: - manual - mcp - api - scheduled - webhook - event - job_recipe_extract - job_recipe_apply - seo_recipe_submit title: WorkflowRunTriggerType description: |- How a workflow run was initiated. - manual: User clicked "Run" in the UI - mcp: First-party MCP client or Skyvern CLI request - api: Direct API call to the run endpoint - scheduled: Triggered by a cron schedule - webhook: Triggered by an external system via the webhook endpoint - event: Triggered by an external event source - job_recipe_extract: Launched by a job recipe extract request - job_recipe_apply: Launched by a job recipe apply request - seo_recipe_submit: Launched by an SEO recipe directory submission 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 RunStatus: type: string enum: - created - queued - running - paused - timed_out - failed - terminated - completed - canceled title: RunStatus BrowserSettingsSource: type: string enum: - workflow_version - session_request - existing_session title: BrowserSettingsSource BrowserSettingsStatus: type: string enum: - verified - mismatch - unapplied - unknown title: BrowserSettingsStatus securitySchemes: ApiKeyAuth: type: apiKey description: Your Skyvern API key from https://app.skyvern.com/settings. in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.