---
# @generated by sylphx-gen 0.1.0 from contracts@e145cc7cf1bc9605f2b27439e5e17ed76a1a2fd7e7021906a013f7565e4a0cd5. Do not edit.
title: "Query an usage report"
description: "`billing.usage_reports.query` (POST /v1/{parent}/usage_reports:query): Queries usage over any time range, bucketed and grouped: the usage summary the console charts."
type: reference
product: platform
summary: "Queries usage over any time range, bucketed and grouped: the usage summary the console charts."
updated: 2026-09-28
nav: false
---

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

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

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

- **Path** `POST https://api.sylphx.com/v1/orgs/acme/usage_reports:query`
- **Scope** `billing:read`
- **Effect** `read` — nothing is written.
- **Collection** [usage_reports](/docs/api/usage_reports)

## Request

| Field | Type | What it is |
| --- | --- | --- |
| `parent` | `string` | The org to query. Required. |
| `start_time` | `timestamp` | The start of the range, inclusive. Required. |
| `end_time` | `timestamp` | The end of the range, exclusive; at most 400 days after `start_time`. Required. |
| `granularity` | `UsageGranularity` | The bucket width. Required. One of `hour`, `day`, `period`. |
| `projects` | `string[]` | Only these projects; empty means every project. |
| `meters` | `string[]` | Only these meter ids; empty means every meter. |
| `group_projects` | `bool` | Group by project in addition to meter. |
| `group_dimensions` | `string[]` | Dimension keys to group by, for example `model`. |

## Response

| Field | Type | What it is |
| --- | --- | --- |
| `rows` | `UsageRow[]` | One row per bucket and group, in time order; at most 10,000. |
| `completeness` | `double` | The share of the range's usage that has reached Billing, from 0 to 1. |
| `compute_time` | `timestamp` | The instant the answer reflects. |
| `watermarks` | `map<string, timestamp>` | Each emitting service's watermark: the time of the oldest usage it has not yet delivered. |

### UsageRow

| Field | Type | What it is |
| --- | --- | --- |
| `start_time` | `timestamp` | The start of the bucket. Output only. |
| `end_time` | `timestamp` | The end of the bucket. Output only. |
| `project` | `string` | The project, when grouped by project. Output only. |
| `meter` | `string` | The meter id. Output only. |
| `dimensions` | `map<string, string>` | The dimensions grouped on. Output only. |
| `quantity` | `int64` | The aggregated quantity, in the meter's base unit. Output only. |
| `service` | `string` | The service that emits the meter. Output only. |

## Errors

- [`UNAUTHENTICATED`](/docs/api/errors/UNAUTHENTICATED) — No valid key or token was presented.
- [`PERMISSION_DENIED`](/docs/api/errors/PERMISSION_DENIED) — The key lacks the method's permission.
- [`INVALID_FIELD`](/docs/api/errors/INVALID_FIELD) — A field failed validation.

Every error arrives in the body [Errors](/docs/platform/errors) describes.

## Examples

**cURL**

```curl
curl -X POST "https://api.sylphx.com/v1/orgs/acme/usage_reports:query" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"end_time":{},"granularity":"hour","start_time":{}}'
```

**TypeScript**

```ts
const response = await sylphx.billing.usageReports.query({ endTime: {}, granularity: 'hour', parent: 'orgs/acme', startTime: {} })
```

**Rust**

```rust
let mut req = sylphx::billing::QueryUsageReportsRequest::default();
req.end_time = Some(Default::default());
req.granularity = sylphx::billing::UsageGranularity::Hour;
req.parent = "orgs/acme".to_string();
req.start_time = Some(Default::default());
let response = sx.billing().usage_reports().query(req).await?;
```

**CLI**

```bash
sylphx billing usage-reports query orgs/acme
```

**MCP**

```json
{ "method_id": "billing.usage_reports.query", "args": {"end_time":{},"granularity":"hour","parent":"orgs/acme","start_time":{}} }
```