Sign in

v60

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-0283227863.6 KB
Runs

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.

get/v1/agents/{workflow_id}/runs

Path parameters

workflow_idstring required

Query parameters

pageinteger

Page number for pagination.

Page number for pagination.

page_sizeinteger

Number of runs to return per page.

Number of runs to return per page.

statusWorkflowRunStatus[] nullable

Filter by one or more run statuses.

Filter by one or more run statuses.

search_keystring 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.

Example:login_url

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_codestring 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.

Example:INVALID_CREDENTIALS

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_startstring date-time nullable

Only include runs created at or after this UTC timestamp (ISO 8601).

Only include runs created at or after this UTC timestamp (ISO 8601).

created_at_endstring date-time nullable

Only include runs created strictly before this UTC timestamp (ISO 8601).

Only include runs created strictly before this UTC timestamp (ISO 8601).

Headers

x-api-keystring nullable

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

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

Response

Successful Response

workflow_run_idstring required
workflow_idstring required
workflow_permanent_idstring required
organization_idstring required
browser_session_idstring nullable
browser_profile_idstring nullable
debug_session_idstring nullable
status'created' | 'queued' | 'running' | 'failed' | 'terminated' | 'canceled' | 'timed_out' | 'completed' | 'paused' required
extra_http_headersobject nullable
cdp_connect_headersobject nullable
webhook_callback_urlstring nullable
webhook_failure_reasonstring nullable
totp_verification_urlstring nullable
totp_identifierstring nullable
failure_reasonstring nullable
failure_categoryobject[] nullable
parent_workflow_run_idstring nullable
workflow_titlestring nullable
max_screenshot_scrollsinteger nullable
max_elapsed_time_minutesinteger nullable
browser_addressstring nullable
run_withstring nullable
job_idstring nullable
depends_on_workflow_run_idstring nullable
sequential_keystring nullable
ai_fallbackboolean nullable
code_genboolean 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_idstring nullable
ignore_inherited_workflow_system_promptboolean
copilot_session_idstring nullable
credits_usedinteger
cached_credits_usedinteger
queued_atstring date-time nullable
started_atstring date-time nullable
finished_atstring date-time nullable
created_atstring date-time required
modified_atstring date-time required

Example response

[
  {
    "proxy_location": {
      "country": "US",
      "subdivision": "CA",
      "city": "New York"
    }
  }
]