Sign in
agent

List runs

List the organization's task and agent runs, newest first, filterable by status, run type, agent, a free-text search term, and failure category. Returns a paginated array of run summaries.

get/v1/runs

Query parameters

pageinteger
page_sizeinteger
statusRunStatus[] nullable
search_keystring nullable

Case-insensitive substring search (min 3 chars for trigram index).

Example:login_url

Case-insensitive substring search (min 3 chars for trigram index).

run_typeRunType[] nullable
workflow_permanent_idstring[] nullable

Filter to runs of these workflows (agents). Repeat the param to include multiple.

Filter to runs of these workflows (agents). Repeat the param to include multiple.

tagsstring[] 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.

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.

failure_categorystring nullable

Exact-match filter on a workflow run's top classifier failure category (failure_category[0].category). Only failed, terminated, and timed_out runs are eligible; canceled runs are never returned by this filter. Applies to run_type=workflow_run only — combined with a task run_type it matches nothing.

Example:ANTI_BOT_DETECTION

Exact-match filter on a workflow run's top classifier failure category (failure_category[0].category). Only failed, terminated, and timed_out runs are eligible; canceled runs are never returned by this filter. Applies to run_type=workflow_run only — combined with a task run_type it matches nothing.

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

task_run_idstring required
run_idstring required
task_run_typestring required
statusstring required
titlestring nullable
started_atstring date-time nullable
finished_atstring date-time nullable
created_atstring date-time required
workflow_permanent_idstring nullable
workflow_deletedboolean
script_runboolean
trigger_type'manual' | 'mcp' | 'api' | 'scheduled' | 'webhook' | 'job_recipe_extract' | 'job_recipe_apply'

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
  • job_recipe_extract: Launched by a job recipe extract request
  • job_recipe_apply: Launched by a job recipe apply request

Changes