# Logs

Generated from contract version `1.0.0` — the same document [`/v1/api/openapi.json`](/api/openapi/) 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/logs/agent-run/{agentRunId}` | [List the log lines of one agent run](#list-the-log-lines-of-one-agent-run) |
| `GET` | `/v1/api/logs/agent/{agentId}` | [List the log lines across one agent's tasks](#list-the-log-lines-across-one-agents-tasks) |
| `GET` | `/v1/api/logs/cycle/{cycleId}` | [List one cycle's log lines](#list-one-cycles-log-lines) |
| `GET` | `/v1/api/logs/project/{projectId}` | [List a project's log lines](#list-a-projects-log-lines) |
| `GET` | `/v1/api/logs/task/{taskId}` | [List one task's log lines](#list-one-tasks-log-lines) |
| `GET` | `/v1/api/logs/trace/{traceId}` | [List the log lines of one trace](#list-the-log-lines-of-one-trace) |

## List the log lines of one agent run

`GET /v1/api/logs/agent-run/{agentRunId}` · operation ID `listAgentRunLogs`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `agentRunId` | 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` | LogEntry[] | Every line one run produced. |
| `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 log lines across one agent's tasks

`GET /v1/api/logs/agent/{agentId}` · operation ID `listAgentLogs`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `agentId` | 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` | LogEntry[] | Lines from every task assigned to this agent, oldest first. Reached through `tasks.agentId`. |
| `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 cycle's log lines

`GET /v1/api/logs/cycle/{cycleId}` · operation ID `listCycleLogs`

**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` | LogEntry[] | Every line recorded against the cycle itself. |
| `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 a project's log lines

`GET /v1/api/logs/project/{projectId}` · operation ID `listProjectLogs`

**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` | LogEntry[] | Lines from every cycle of the project, oldest first. A line with no cycle is not reachable this way. |
| `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 log lines

`GET /v1/api/logs/task/{taskId}` · operation ID `listTaskLogs`

**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` | LogEntry[] | Every line recorded against the task. |
| `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 log lines of one trace

`GET /v1/api/logs/trace/{traceId}` · operation ID `listTraceLogs`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `traceId` | 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` | LogEntry[] | Every line sharing this trace id — the same correlation the run, event and audit rows carry. |
| `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 reference](/api/reference/)
  [API & OpenAPI](/api/openapi/)
  [TypeScript SDK](/sdk/typescript/)
  [CLI reference](/reference/cli/)