---
# @generated by sylphx-gen 0.1.0 from contracts@e145cc7cf1bc9605f2b27439e5e17ed76a1a2fd7e7021906a013f7565e4a0cd5. Do not edit.
title: "Usage reports"
description: "The `usage_reports` collection of Sylphx Billing: A UsageReport is an org's usage summary for one billing period, rolled up per project, meter, and dimensions, with how complete it is."
type: reference
product: platform
summary: "A UsageReport is an org's usage summary for one billing period, rolled up per project, meter, and dimensions, with how complete it is."
updated: 2026-09-28
order: 900
---

> **This method is not served on the public API.** `api.sylphx.com` does not route this call: its backend is not deployed behind the public API, or does not implement the call. This page documents the contract. It is kept out of the sidebar and of search engines.

A UsageReport is an org's usage summary for one billing period, rolled up per project, meter, and dimensions, with how complete it is. The id is the period, for example `orgs/{org}/usage_reports/2026-11`.

**Service** Sylphx Billing · **Resource type** `billing.sylphx.com/UsageReport` · **Name pattern** `orgs/{org}/usage_reports/{usage_report}` · **Shape** `record`

**Not available yet.** Sylphx Billing is declared in the registry but no backend serves it: every call answers `501` with the problem code `UNIMPLEMENTED`.

## Fields

| Field | Type | What it is |
| --- | --- | --- |
| `name` | `string` | `orgs/{org}/usage_reports/{YYYY-MM}`. |
| `uid` | `string` | `usr_<cell><ulid>`. Output only. |
| `meta` | `ResourceMeta` | Resource metadata. Output only. |
| `period_start_time` | `timestamp` | The start of the period. Output only. |
| `period_end_time` | `timestamp` | The end of the period. Output only. |
| `lines` | `UsageLine[]` | One line per project, meter, and dimension set. Output only. |
| `completeness` | `double` | The share of the period's usage that has reached Billing, from 0 to 1, from every emitter's watermark. Output only. |
| `compute_time` | `timestamp` | The instant the report reflects. Output only. |
| `invoice` | `string` | The period's invoice, once one exists. Output only. |
| `watermarks` | `map<string, timestamp>` | Each emitting service's watermark: the time of the oldest usage it has not yet delivered. Output only. |

## Methods

Every method of the collection, in the registry's order, with the scope it
needs. The full request, response and examples are one link away.

| Method | Call | What it does |
| --- | --- | --- |
| `GET` | [`get`](/docs/api/usage_reports#get) | Gets an usage report. |
| `GET` | [`list`](/docs/api/usage_reports#list) | Lists an org's usage reports, one per billing period. |
| `POST` | [`query`](/docs/api/usage_reports#query) | Queries usage over any time range, bucketed and grouped: the usage summary the console charts. Reads rollups; never raw events. |

## get

Gets an usage report.

`GET https://api.sylphx.com/v1/orgs/acme/usage_reports/usage-report` · scope `billing:read` · effect `read` · not available yet · [Request, response and examples](/docs/api/usage_reports/get)

## list

Lists an org's usage reports, one per billing period.

`GET https://api.sylphx.com/v1/orgs/acme/usage_reports` · scope `billing:read` · effect `read` · not available yet · paginated · [Request, response and examples](/docs/api/usage_reports/list)

## query

Queries usage over any time range, bucketed and grouped: the usage summary the console charts. Reads rollups; never raw events.

`POST https://api.sylphx.com/v1/orgs/acme/usage_reports:query` · scope `billing:read` · effect `read` · not available yet · [Request, response and examples](/docs/api/usage_reports/query)