---
title: "Get all runs by agent"
method: GET
path: "/v1/agents/{workflow_id}/runs"
tags: ["Runs"]
---

# Get all runs by agent

`GET /v1/agents/{workflow_id}/runs`

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.

## Path parameters

- `workflow_id` string, required

## Query parameters

- `page` integer — Page number for pagination.
- `page_size` integer — Number of runs to return per page.
- `status` WorkflowRunStatus[], nullable — Filter by one or more run statuses.
- `search_key` string, nullable — 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.
- `error_code` string, nullable — 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.
- `created_at_start` string, date-time, nullable — Only include runs created at or after this UTC timestamp (ISO 8601).
- `created_at_end` string, date-time, nullable — Only include runs created strictly before this UTC timestamp (ISO 8601).
- `tags` string[], nullable — 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.
- `include_child_runs` boolean — Include child workflow runs — runs started from inside another workflow run. Excluded by default so the history shows only top-level runs.

## Headers

- `x-api-key` string, nullable — Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.

## Response `200`

Successful Response

- WorkflowRun[]
  - `workflow_run_id` string, required
  - `workflow_id` string, required
  - `workflow_permanent_id` string, required
  - `organization_id` string, required
  - `browser_session_id` string, nullable
  - `browser_profile_id` string, nullable
  - `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
  - `browser_sink_profile_id` string, nullable
  - `start_fresh_browser` boolean, nullable
  - `reuse_browser_session` boolean, nullable
  - `debug_session_id` string, nullable
  - `status` 'created' | 'queued' | 'running' | 'failed' | 'terminated' | 'canceled' | 'timed_out' | 'completed' | 'paused', required
  - `extra_http_headers` object, nullable
  - `cdp_connect_headers` object, nullable
  - `proxy_location` union
    - '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_callback_url` string, nullable
  - `webhook_failure_reason` string, nullable
  - `totp_verification_url` string, nullable
  - `totp_identifier` string, nullable
  - `failure_reason` string, nullable
  - `failure_category` object[], nullable
  - `retried_from_workflow_run_id` string, nullable
  - `fallback_attempt` integer, nullable
  - `parent_workflow_run_id` string, nullable
  - `workflow_title` string, nullable
  - `max_screenshot_scrolls` integer, nullable
  - `max_elapsed_time_minutes` integer, nullable
  - `browser_address` string, nullable
  - `run_with` string, nullable
  - `script_run` ScriptRunResponse
    - `ai_fallback_triggered` boolean
    - `script_id` string, nullable
    - `script_revision_id` string, nullable
  - `job_id` string, nullable
  - `depends_on_workflow_run_id` string, nullable
  - `sequential_key` string, nullable
  - `sequential_credential_id` string, nullable
  - `ai_fallback` boolean, nullable
  - `code_gen` boolean, nullable
  - `trigger_type` 'manual' | 'mcp' | 'api' | 'scheduled' | 'webhook' — 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
  - `workflow_schedule_id` string, nullable
  - `ignore_inherited_workflow_system_prompt` boolean
  - `copilot_session_id` string, nullable
  - `credits_used` integer
  - `cached_credits_used` integer
  - `queued_at` string, date-time, nullable
  - `started_at` string, date-time, nullable
  - `finished_at` string, date-time, nullable
  - `created_at` string, date-time, required
  - `modified_at` string, date-time, required

## Other responses

- `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/revisions/89037b86e004/schema)