Skip to main content
GET
List project runs

Authorizations

Authorization
string
header
required

Use a JWT bearer token or a Veryfront API key in the Authorization header.

Path Parameters

project_reference
string
required
Minimum string length: 1

Query Parameters

task_id
string

Discover agent runs with this persisted task identity across conversations. Matches canonical task metadata or the first enqueue request; results are not task authorization evidence.

Required string length: 1 - 200
Pattern: ^[a-zA-Z0-9][a-zA-Z0-9._:-]*$
limit
integer
default:100
Required range: 1 <= x <= 200
cursor
string
Minimum string length: 1
sort_by
enum<string>
default:created_at
Available options:
created_at,
status,
duration
sort_order
enum<string>
default:desc
Available options:
asc,
desc
status

Only runs in one of these statuses (pending, running, waiting, completed, failed, cancelled). Comma-separated and/or repeated; duplicates are ignored; at most 32 values.

kind

Only runs of one of these kinds (agent, workflow, task, eval). Comma-separated and/or repeated; duplicates are ignored; at most 16 values. Combined with task_id, which already restricts results to agent runs, a kind list without agent yields an empty page.

trigger_kind

Only runs started by one of these trigger kinds (manual, schedule, webhook, api). Comma-separated and/or repeated; duplicates are ignored; at most 16 values. Runs without a recorded trigger kind (trigger_kind null) match no value and are excluded whenever this filter is set.

root_only
enum<string>
default:false

true lists only top-level runs (parent_run_id null). Defaults to false.

Available options:
true,
false
parent_run_id
string

Only the direct children of the run with this ID that the caller can see. Cannot be combined with root_only=true.

Required string length: 1 - 128
target

Only runs whose target equals one of these values exactly, for example task:sync-data for the runs of one project task. Comma-separated and/or repeated; duplicates are ignored; at most 16 values. Values are split on commas, so a target that contains a comma cannot be matched. Not the same as task_id, which is an agent task identity, not a project task ID.

workflow_id

Only runs of one of these workflow IDs. Only workflow runs carry a workflow_id, so other kinds never match. Comma-separated and/or repeated; duplicates are ignored; at most 16 values.

schedule_id
string<uuid>

Only runs fired by this schedule, of every kind (agent, task and workflow). A schedule of another project yields an empty page.

Response

200 - application/json

Project runs

data
object[]
required
page_info
object
required