Skyvern: List runs

← Runs operations · Get started

Operation skyvern.get_runs_v2_v1_runs_get

Provider route: GET /v1/runs. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/skyvern with npm, or alter-sdk-skyvern with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { SkyvernIntegration } from "@alter-ai/skyvern";

async function execute(input: Parameters<SkyvernIntegration["runs"]["getRunsV2"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new SkyvernIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.runs.getRunsV2(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_skyvern import SkyvernIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = SkyvernIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.runs.get_runs_v2(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
query	object	Optional	Additional keys: not allowed
query.page	integer	Optional	Default: 1 Maximum: 100 Minimum: 1
query.page_size	integer	Optional	Default: 10 Maximum: 100 Minimum: 1
query.status	JSON	Optional
query.status (anyOf 1)	array	Alternative
query.status (anyOf 1)[]	string	Each item	One of: created, queued, running, paused, timed_out, failed, terminated, completed, canceled
query.status (anyOf 2)	null	Alternative
query.search_key	JSON	Optional	Case-insensitive substring search (min 3 chars for trigram index) across the run’s title, URL, run ID, agent (workflow) ID and inputs, plus a workflow run’s webhook callback URL. A complete browser profile ID, browser session ID or credential ID matches the run that used it exactly (no substring match). A complete workflow run ID matches that run. A complete task ID matches the workflow run the task ran in, when this list includes that run, or the standalone task itself where standalone tasks are listed. A complete browser profile, browser session, workflow run or task ID is matched against those identifiers only, not the text fields. A credential ID matches when it is the run’s sequential credential, the credential the run selected from a pool or fell back to, or the credential bound by a credential parameter on the run’s workflow version when the run was created and the run recorded no selection for it. Browser profile and credential IDs apply to workflow runs; a browser session ID also matches a standalone task that used it.
query.search_key (anyOf 1)	string	Alternative	Minimum length: 3
query.search_key (anyOf 2)	null	Alternative
query.run_type	JSON	Optional
query.run_type (anyOf 1)	array	Alternative
query.run_type (anyOf 1)[]	string	Each item	One of: task_v1, task_v2, task_v3, workflow_run, openai_cua, anthropic_cua, ui_tars, yutori_navigator
query.run_type (anyOf 2)	null	Alternative
query.workflow_permanent_id	JSON	Optional	Filter to runs of these workflows (agents). Repeat the param to include multiple.
query.workflow_permanent_id (anyOf 1)	array	Alternative	Maximum items: 50
query.workflow_permanent_id (anyOf 1)[]	string	Each item
query.workflow_permanent_id (anyOf 2)	null	Alternative
query.tags	JSON	Optional	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.
query.tags (anyOf 1)	array	Alternative	Maximum items: 20
query.tags (anyOf 1)[]	string	Each item
query.tags (anyOf 2)	null	Alternative
query.failure_category	JSON	Optional	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.
query.failure_category (anyOf 1)	string	Alternative	Maximum length: 100
query.failure_category (anyOf 2)	null	Alternative

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	array	Root
$[]	Model	Each item	Expand List runs — response body — item

Referenced models: List runs — response body — item

Schemas

List runs — response body — item

Field	Type	Presence	Description and constraints
$	object	Root	Lightweight run-history item backed by the task_runs table.
created_at	string	Required within parent	Format: date-time
created_by	JSON	Optional	ID of the user who started the run
created_by (anyOf 1)	string	Alternative
created_by (anyOf 2)	null	Alternative
finished_at	JSON	Optional
finished_at (anyOf 1)	string	Alternative	Format: date-time
finished_at (anyOf 2)	null	Alternative
run_id	string	Required within parent
script_run	boolean	Optional	Default: false
started_at	JSON	Optional
started_at (anyOf 1)	string	Alternative	Format: date-time
started_at (anyOf 2)	null	Alternative
status	string	Required within parent
task_run_id	string	Required within parent
task_run_type	string	Required within parent
title	JSON	Optional
title (anyOf 1)	string	Alternative
title (anyOf 2)	null	Alternative
trigger_type	JSON	Optional
trigger_type (anyOf 1)	Model	Alternative	Expand List runs — response body — item trigger type How a workflow run was initiated
trigger_type (anyOf 2)	null	Alternative
workflow_deleted	boolean	Optional	Default: false
workflow_permanent_id	JSON	Optional
workflow_permanent_id (anyOf 1)	string	Alternative
workflow_permanent_id (anyOf 2)	null	Alternative

Referenced models: List runs — response body — item trigger type How a workflow run was initiated

List runs — response body — item trigger type How a workflow run was initiated

Field	Type	Presence	Description and constraints
$	string	Root	How a workflow run was initiated. - manual: User clicked "Run" in the UI - mcp: First-party MCP client or Skyvern CLI 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 - event: Triggered by an external event source - job_recipe_extract: Launched by a job recipe extract request - job_recipe_apply: Launched by a job recipe apply request - seo_recipe_submit: Launched by an SEO recipe directory submission Known values: manual, mcp, api, scheduled, webhook, event, job_recipe_extract, job_recipe_apply, seo_recipe_submit

Policy, approvals and errors

SDK function policy ID: skyvern.get_runs_v2_v1_runs_get. Catalog operation: get_runs_v2_v1_runs_get. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Official provider source