> ## 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. ### search_key Case-insensitive substring search across: workflow run ID, parameter key, parameter description, run parameter value, and extra HTTP headers. Soft-deleted parameter definitions are excluded. ### 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 - url: https://api-staging.skyvern.com x-fern-server-name: Staging - url: http://localhost:8000 x-fern-server-name: Local 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. ### search_key Case-insensitive substring search across: workflow run ID, parameter key, parameter description, run parameter value, and extra HTTP headers. Soft-deleted parameter definitions are excluded. ### 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 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 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, and extra HTTP headers. A run is returned if any of these fields match. Soft-deleted parameter definitions are excluded from key/description matching. examples: - login_url - credential_value - wr_abc123 title: Search Key description: >- Case-insensitive substring search across: workflow run ID, parameter key, parameter description, run parameter value, and extra HTTP headers. A run is returned if any of these fields match. Soft-deleted parameter definitions are excluded from key/description matching. - 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. - 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. 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' 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' 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 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 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 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 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. 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 title: WorkflowRunTriggerType description: |- How a workflow run was initiated. - manual: User clicked "Run" in the UI - mcp: First-party MCP client 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 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 ````