---
title: "Get Runs V2"
method: GET
path: "/v1/runs"
tags: ["agent"]
---

# Get Runs V2

`GET /v1/runs`

## Query parameters

- `page` integer
- `page_size` integer
- `status` RunStatus[], nullable
- `search_key` string, nullable — Case-insensitive substring search (min 3 chars for trigram index).
- `run_type` RunType[], nullable
- `workflow_permanent_id` string[], nullable — Filter to runs of these workflows (agents). Repeat the param to include multiple.
- `tags` string[], 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.

## Headers

- `x-api-key` string, nullable — Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.

## Response `200`

Successful Response

- TaskRunListItem[]
  - `task_run_id` string, required
  - `run_id` string, required
  - `task_run_type` string, required
  - `status` string, required
  - `title` string, nullable
  - `started_at` string, date-time, nullable
  - `finished_at` string, date-time, nullable
  - `created_at` string, date-time, required
  - `workflow_permanent_id` string, nullable
  - `workflow_deleted` boolean
  - `script_run` boolean
  - `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

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/skyvern-ai/apis/skyvern-api-2.md) · [All operations](https://skmtc.net/skyvern-ai/apis/skyvern-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/skyvern-ai/skyvern-api-2/revisions/5116249dfff3/schema)