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'

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

Changes

Changed in 7 of the 86 revisions of this API.8

  • b89637d05de91See the full diff
    • ○

      added the new optional query request parameter failure_category

      new-optional-request-parameter

  • 0c5e6f1a3df91See the full diff
    • ○

      added the enum value task_v3 to the property anyOf[subschema #1]/items/ of the query request parameter run_type

      request-parameter-property-enum-value-added

  • 5987635eae7d1See the full diff
    • ○

      added the new optional query request parameter workflow_permanent_id

      new-optional-request-parameter

  • b7fa64d357691See the full diff
    • ○

      added the enum value paused to the property anyOf[subschema #1]/items/ of the query request parameter status

      request-parameter-property-enum-value-added

  • 4aae03aca7da2See the full diff
    • ○

      added the new optional query request parameter run_type

      new-optional-request-parameter

    • ○

      added the new optional query request parameter tags

      new-optional-request-parameter

  • 3c39ee1fef001See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

  • 3a3616091b661See the full diff
    • ○

      endpoint added

      endpoint-added

    This revision also has 10 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog