Reports

Reports summarize workspace portfolio health, billing, usage and customers. Agency members receive authorized workspace views; client collaborators receive only the reports and projects available to them.

See the OpenAPI document for schemas and operation IDs.

Prerequisites

• Protected operations require an API key in x-api-key or a browser session cookie; some actions require a verified user session
• Tenant-scoped operations use X-Organization-Id; browser sessions can use their active workspace. Discovery and personal-workspace bootstrap do not require an active workspace
• 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.
X-Client-Portal	header	no	string	The agency Workspace ID for a signed-in client’s portal requests. A verified user session and portal membership are required; API keys cannot authenticate portal access. This header does not grant agency administration access.

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.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

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.
X-Client-Portal	header	no	string	The agency Workspace ID for a signed-in client’s portal requests. A verified user session and portal membership are required; API keys cannot authenticate portal access. This header does not grant agency administration access.

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.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

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.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

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.
X-Client-Portal	header	no	string	The agency Workspace ID for a signed-in client’s portal requests. A verified user session and portal membership are required; API keys cannot authenticate portal access. This header does not grant agency administration access.

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.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

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.
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

The response table for each operation lists its documented errors. Common status codes include:

• 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 — check the resource ID and your access to the selected Workspace.
• 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

Browse endpoints, request fields and responses.

API & OpenAPI

Download the contract, generate a client, and read the compatibility policy.

TypeScript SDK

Auth, retries, typed errors, uploads and streaming, already built.

CLI reference

The same operations from a terminal, with a stable JSON envelope.