Agent runs

Generated from contract version 1.0.0 — the same document /v1/api/openapi.json serves.

Prerequisites

• An API key in x-api-key, or a browser session cookie
• X-Organization-Id naming the workspace to act in, unless the session already has an active one
• The base URL for your deployment, https://server.hlix.ai by default

Operations

Method	Path	Operation
GET	/v1/api/agent-runs/{id}/snapshot	Get one run’s recorded input and output
GET	/v1/api/agent-runs/cycle/{cycleId}	List the runs of every task in a cycle
GET	/v1/api/agent-runs/project/{projectId}	List every run of a project
GET	/v1/api/agent-runs/task/{taskId}	List the runs recorded against one task
GET	/v1/api/agent-runs/task/{taskId}/timeline	List one task’s runs in start order

Get one run’s recorded input and output

GET /v1/api/agent-runs/{id}/snapshot · operation ID getAgentRunSnapshot

Parameters

Name	In	Required	Type	Description
id	path	yes	string
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Responses

Status	Body	Description
200	AgentRunSnapshot	The run, with the text its harness recorded.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	No such run in this workspace.

List the runs of every task in a cycle

GET /v1/api/agent-runs/cycle/{cycleId} · operation ID listCycleAgentRuns

Parameters

Name	In	Required	Type	Description
cycleId	path	yes	string
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Responses

Status	Body	Description
200	AgentRunSummary[]	Cost and timing per run, start-ordered. Snapshots are not included.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

List every run of a project

GET /v1/api/agent-runs/project/{projectId} · operation ID listProjectAgentRuns

Parameters

Name	In	Required	Type	Description
projectId	path	yes	string
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Responses

Status	Body	Description
200	AgentRunSummary[]	Task-execution runs plus the planning and chat runs attributed to the project directly.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

List the runs recorded against one task

GET /v1/api/agent-runs/task/{taskId} · operation ID listTaskAgentRuns

Parameters

Name	In	Required	Type	Description
taskId	path	yes	string
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Responses

Status	Body	Description
200	AgentRun[]	Every run on the task, whole rows. Empty when the task never ran.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

List one task’s runs in start order

GET /v1/api/agent-runs/task/{taskId}/timeline · operation ID listTaskAgentRunTimeline

Parameters

Name	In	Required	Type	Description
taskId	path	yes	string
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Responses

Status	Body	Description
200	AgentRun[]	The same rows as the task list, ordered oldest-first by start time.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

If a request fails

These apply to every operation on this page.

• 400 — the body failed schema validation, or the request named no active organization. A ValidationError body carries the failing fields; an ApiError body carries only error.
• 401 — no valid session or API key.
• 403 — authenticated, but not a member of the named organization, or a client collaborator without the required access.
• 404 — no such resource in this workspace. Absent and not-visible are deliberately the same answer; do not infer cross-tenant existence from it.
• 409 — the expected revision or state is stale, or another operation currently owns the transition.
• 500 — the operation failed server-side. Retry only where an idempotency key makes that safe.

Next steps

API referenceEvery resource in the published contract, and what is deliberately not in it.

API & OpenAPIDownload the contract, generate a client, and read the compatibility policy.

TypeScript SDKAuth, retries, typed errors, uploads and streaming, already built.

CLI referenceThe same operations from a terminal, with a stable JSON envelope.