List workflow 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…)
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)

Soft-deleted parameter definitions are excluded from key/description matching. A run is returned if any of the fields above contain the search term.

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

GET /v1/workflows/runs

List workflow runs

cURL

curl --request GET \
  --url https://api.skyvern.com/v1/workflows/runs

200

[
  {
    "workflow_run_id": "<string>",
    "workflow_id": "<string>",
    "workflow_permanent_id": "<string>",
    "organization_id": "<string>",
    "status": "created",
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "browser_session_id": "<string>",
    "browser_profile_id": "<string>",
    "debug_session_id": "<string>",
    "extra_http_headers": {},
    "proxy_location": "RESIDENTIAL",
    "webhook_callback_url": "<string>",
    "webhook_failure_reason": "<string>",
    "totp_verification_url": "<string>",
    "totp_identifier": "<string>",
    "failure_reason": "<string>",
    "failure_category": [
      {}
    ],
    "parent_workflow_run_id": "<string>",
    "workflow_title": "<string>",
    "max_screenshot_scrolls": 123,
    "browser_address": "<string>",
    "run_with": "<string>",
    "script_run": {
      "ai_fallback_triggered": false
    },
    "job_id": "<string>",
    "depends_on_workflow_run_id": "<string>",
    "sequential_key": "<string>",
    "ai_fallback": true,
    "code_gen": true,
    "trigger_type": "manual",
    "workflow_schedule_id": "<string>",
    "queued_at": "2023-11-07T05:31:56Z",
    "started_at": "2023-11-07T05:31:56Z",
    "finished_at": "2023-11-07T05:31:56Z"
  }
]

Headers

x-api-key · string | null

Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.

Query Parameters

page · integer · default: 1

Page number for pagination.

Required range: x >= 1

page_size · integer · default: 10

Number of runs to return per page.

Required range: x >= 1

status · enum<string>[] | null

Filter by one or more run statuses.

Available options: created, queued, running, failed, terminated, canceled, timed_out, completed, paused

search_key · string | null

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.

Maximum string length: 500

Example:

"login_url"

error_code · string | null

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.

Maximum string length: 500

Example:

"INVALID_CREDENTIALS"

Response

200

application/json

Successful Response

workflow_run_id · string · required

workflow_id · string · required

workflow_permanent_id · string · required

organization_id · string · required

status · enum<string> · required

Available options: created, queued, running, failed, terminated, canceled, timed_out, completed, paused

created_at · string<date-time> · required

modified_at · string<date-time> · required

browser_session_id · string | null

browser_profile_id · string | null

debug_session_id · string | null

extra_http_headers · Extra Http Headers · object

Show child attributes

proxy_location · enum<string> GeoTarget · object Proxy Location · object

Available options: 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_ISP, NONE

webhook_callback_url · string | null

webhook_failure_reason · string | null

totp_verification_url · string | null

totp_identifier · string | null

failure_reason · string | null

failure_category · Failure Category · object[] | null

parent_workflow_run_id · string | null

workflow_title · string | null

max_screenshot_scrolls · integer | null

browser_address · string | null

run_with · string | null

script_run · ScriptRunResponse · object

Show child attributes

job_id · string | null

depends_on_workflow_run_id · string | null

sequential_key · string | null

ai_fallback · boolean | null

code_gen · boolean | null

trigger_type · enum<string> | null

How a workflow run was initiated.

• manual: User clicked "Run" in the UI
• api: Direct API call to the run endpoint
• scheduled: Triggered by a cron schedule
• webhook: Triggered by an external system via the webhook endpoint

Available options: manual, api, scheduled, webhook

workflow_schedule_id · string | null

queued_at · string<date-time> | null

started_at · string<date-time> | null

finished_at · string<date-time> | null