GET /v1/usage/events — Atom Files Developers

← API referenceUsage & billing · API access unavailable

API REFERENCE / USAGE

`GET` /v1/usage/events

Page through metering records for reconciliation. Each event has a stable ID, timestamp, meter, quantity, and related transfer or operation ID. Do not expose private peer addresses, Mac paths, or provider credentials.

Request fields

Location	Field	Type	Required	Description
Header	`Authorization`	string	Yes	Credential scoped to the authorized resource.
Query	`from`	string (date)	No	Period start.
Query	`to`	string (date)	No	Period end.
Query	`meter`	string	No	Meter filter.
Query	`cursor`	string	No	Opaque pagination cursor.

Request example

Example request

GET /v1/usage/events?meter=relay_egress_bytes
Authorization: Bearer <scoped token>

HTTP status codes

Status	Meaning
`200 OK`	Success response shown below.
`400 Bad Request`	Invalid period, meter, or cursor.
`401 Unauthorized`	Missing, expired, or invalid credential.
`403 Forbidden`	Credential is valid but lacks the required scope or role.
`429 Too Many Requests`	Rate limit reached; honor Retry-After when provided.
`503 Service Unavailable`	Service temporarily unavailable; retry safely.

Response fields

Field	Type	Example
`items`	object[]	[1 shown]
`items[].id`	string	usage_123
`items[].meter`	string	relay_egress_bytes
`items[].quantity`	integer	16777216
`items[].unit`	string	byte
`items[].operation_id`	string	op_456
`items[].occurred_at`	string (date-time)	2026-10-20T18:00:00Z
`next_cursor`	string \| null	null
`observed_through`	string (date-time)	2026-10-20T18:00:00Z

Response example

Example response

200 OK
Content-Type: application/json

{
  "items": [
    {
      "id": "usage_123",
      "meter": "relay_egress_bytes",
      "quantity": 16777216,
      "unit": "byte",
      "operation_id": "op_456",
      "occurred_at": "2026-10-20T18:00:00Z"
    }
  ],
  "next_cursor": null,
  "observed_through": "2026-10-20T18:00:00Z"
}

How it works

Filtersfrom, to, meter, and opaque cursor.

CorrectionsRetain auditability if an event is adjusted; do not rewrite history invisibly.

FreshnessReturn observed_through because aggregates may lag activity.

Retention, exact event schema, and meter IDs remain design decisions.