# Reports

**Reports** are aggregate, client-safe views over a workspace: portfolio health, billing, usage, and customers. They read across projects and never expose another workspace's data.

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/reports` | [Get the current portfolio overview](#get-the-current-portfolio-overview) |
| `GET` | `/v1/api/reports/billing` | [Get billing health](#get-billing-health) |
| `GET` | `/v1/api/reports/customers` | [List customer portfolio reports](#list-customer-portfolio-reports) |
| `GET` | `/v1/api/reports/projects` | [List project health reports](#list-project-health-reports) |
| `GET` | `/v1/api/reports/usage` | [Get agent usage and cost](#get-agent-usage-and-cost) |

## Get the current portfolio overview

`GET /v1/api/reports` · operation ID `getOverviewReport`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `period` | query | no | string | Rolling reporting window such as `30d`; clamped to 1–365 days. |
| `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` | AgencyOverviewReport \| ClientOverviewReport | The agency portfolio report, or the caller's client-safe overview. |
| `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. |

## Get billing health

`GET /v1/api/reports/billing` · operation ID `getBillingReport`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `period` | query | no | string | Rolling reporting window such as `30d`; clamped to 1–365 days. |
| `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` | AgencyBillingReport \| ClientBillingReport | Agency billing health, or the invoices visible to this client. |
| `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. |

## List customer portfolio reports

`GET /v1/api/reports/customers` · operation ID `listCustomerReports`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `period` | query | no | string | Rolling reporting window such as `30d`; clamped to 1–365 days. |
| `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` | CustomersReport | Each customer counted once across all projects. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is a client collaborator; this portfolio view is agency-only. |

## List project health reports

`GET /v1/api/reports/projects` · operation ID `listProjectReports`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `period` | query | no | string | Rolling reporting window such as `30d`; clamped to 1–365 days. |
| `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` | AgencyProjectsReport \| ClientProjectsReport | Agency project health, or only the projects visible to this client. |
| `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. |

## Get agent usage and cost

`GET /v1/api/reports/usage` · operation ID `getUsageReport`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `period` | query | no | string | Rolling reporting window such as `30d`; clamped to 1–365 days. |
| `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` | UsageReport | Agent runs, tokens, and cost for the reporting window. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is a client collaborator; this portfolio view is agency-only. |

## 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/)