> ## 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 by agent > List runs for a specific workflow. Supports filtering by **status**, **search_key**, and **error_code**. All filters are combined with **AND** logic. Unindexed free-text searches can paginate only through the first 1,000 matching runs. Split larger exports into narrower `created_at_start`/`created_at_end` windows or use a complete run/task ID. ### search_key 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. ### error_code 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`. ### include_child_runs Child runs — runs this workflow started from inside another workflow run — are **excluded by default**, so the history shows only top-level runs. Pass `include_child_runs=true` to list them as well; every run carries a `parent_workflow_run_id` that is `null` for top-level runs. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/agents/{workflow_id}/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/{workflow_id}/runs: get: tags: - Runs summary: Get all runs by agent description: >- List runs for a specific workflow. Supports filtering by **status**, **search_key**, and **error_code**. All filters are combined with **AND** logic. Unindexed free-text searches can paginate only through the first 1,000 matching runs. Split larger exports into narrower `created_at_start`/`created_at_end` windows or use a complete run/task ID. ### search_key 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. ### error_code 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`. ### include_child_runs Child runs — runs this workflow started from inside another workflow run — are **excluded by default**, so the history shows only top-level runs. Pass `include_child_runs=true` to list them as well; every run carries a `parent_workflow_run_id` that is `null` for top-level runs. operationId: get_workflow_runs_by_id_v1_workflows__workflow_id__runs_get parameters: - name: workflow_id in: path required: true schema: type: string title: Workflow Id - 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. 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. - 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 UTC timestamp (ISO 8601). title: Created At Start description: Only include runs created at or after this UTC timestamp (ISO 8601). - 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 UTC timestamp (ISO 8601). title: Created At End description: >- Only include runs created strictly before this UTC timestamp (ISO 8601). - name: tags in: query required: false schema: anyOf: - type: array items: type: string maxItems: 20 - type: 'null' description: >- Filter by run tags. Each term is a label (`production`), a group (`env:*`), or a group:label (`env:prod`). Repeat the param or comma-separate (`?tags=env:prod,env:staging`). AND across distinct terms, OR within a group's labels (`?tags=customer:acme,env:prod,env:staging` -> customer=acme AND env in (prod, staging)). A label term matches the value across any/no group. Matches current tag values only. examples: - env:prod - production - env:* - customer:acme,env:prod title: Tags description: >- Filter by run tags. Each term is a label (`production`), a group (`env:*`), or a group:label (`env:prod`). Repeat the param or comma-separate (`?tags=env:prod,env:staging`). AND across distinct terms, OR within a group's labels (`?tags=customer:acme,env:prod,env:staging` -> customer=acme AND env in (prod, staging)). A label term matches the value across any/no group. Matches current tag values only. - name: include_child_runs in: query required: false schema: type: boolean description: >- Include child workflow runs — runs started from inside another workflow run. Excluded by default so the history shows only top-level runs. default: false title: Include Child Runs description: >- Include child workflow runs — runs started from inside another workflow run. Excluded by default so the history shows only top-level runs. responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/WorkflowRun' title: >- Response Get Workflow Runs By Id V1 Workflows Workflow Id 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.