usage

GET /usage

Read metered usage rollups

Flat rollup rows for the credential's project (003 §3: the project is resolved from the credential — a request-supplied project id is validated, never trusted). Reads Cloud SQL rollups only, never the raw BigQuery stream (WP-B1 req 6). Defaults to the last 30 days at granularity=day; start \> end or a range wider than 366 days fail with 400 invalid_argument. Bounds are inclusive on period_start. The flat-rollup-row shape is normative — no nested time series or period totals; clients group/aggregate client-side (WP-B1 Exposes). Requires the read scope; console sessions scope tenancy via the X-Tessera-Project + X-Tessera-Environment headers (003 §2).

Operation ID: getUsage · Service: gateway-api

Authentication

• apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
• consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters

Name	In	Required	Type	Description
cursor	query	no	string	Opaque pagination cursor from a previous response's next_cursor.
end	query	no	string	Inclusive upper bound on period_start (RFC 3339 UTC). Defaults to now.
granularity	query	no	string	Rollup granularity; defaults to day.
limit	query	no	integer	Page size (cursor pagination, 003 §1). Maximum 200.
metric	query	no	string	Restrict to one metric (002 §11 closed set).
start	query	no	string	Inclusive lower bound on period_start (RFC 3339 UTC). Defaults to 30 days before end.

Pagination

Cursor pagination (003 §1): pass limit (max 200) and cursor; the response is the pagination envelope — data plus next_cursor (null on the last page).

Responses

Status	Schema	Description
200	UsagePage	Page of usage rollup rows.
default	ErrorEnvelope	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

Errors

Every non-2xx response uses the 003 §1 error envelope; error.request_id matches the X-Request-Id response header, and the HTTP status always matches error.code:

{
  "error": {
    "code": "invalid_argument",
    "details": [
      {
        "type": "field_violation"
      }
    ],
    "message": "human-readable",
    "request_id": "req_01hxample"
  }
}

Closed error-code set (003 §1): invalid_argument, unauthenticated, permission_denied, not_found, already_exists, failed_precondition, resource_exhausted, internal, unavailable.

resource_exhausted responses (HTTP 429) additionally carry retry_after_seconds. See ErrorEnvelope.