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 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	/v1/api/reports/billing	Get billing health
GET	/v1/api/reports/customers	List customer portfolio reports
GET	/v1/api/reports/projects	List project health reports
GET	/v1/api/reports/usage	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 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.