GET /v1/usage/summary — Atom Files Developers

← API referenceUsage & billing · API access unavailable

API REFERENCE / USAGE

`GET` /v1/usage/summary

See observed activity for a bounded time window. Separate the route that delivered bytes from the units that may be billed. An integration can see its own usage; account-wide totals require an owner or billing-admin grant.

Request fields

Location	Field	Type	Required	Description
Header	`Authorization`	string	Yes	Credential scoped to the authorized resource.
Query	`from`	string (date)	Yes	Inclusive period start.
Query	`to`	string (date)	Yes	Exclusive period end.

Request example

Example request

GET /v1/usage/summary?from=2026-10-01&to=2026-11-01
Authorization: Bearer <scoped token>

HTTP status codes

Status	Meaning
`200 OK`	Success response shown below.
`400 Bad Request`	Invalid reporting period.
`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
`period`	object	{…}
`period.from`	string (date)	2026-10-01
`period.to`	string (date)	2026-11-01
`status`	string	estimated
`observed_through`	string (date-time)	2026-10-20T18:00:00Z
`transfer_bytes`	object	{…}
`transfer_bytes.direct_peer`	integer	104857600
`transfer_bytes.relay`	integer	16777216
`transfer_bytes.cloud_egress`	integer	0
`api_requests`	integer	42
`billable`	object[]	[1 shown]
`billable[].meter`	string	relay_egress_bytes
`billable[].quantity`	integer	16777216
`billable[].unit`	string	byte

Response example

Example response

200 OK
Content-Type: application/json

{
  "period": {
    "from": "2026-10-01",
    "to": "2026-11-01"
  },
  "status": "estimated",
  "observed_through": "2026-10-20T18:00:00Z",
  "transfer_bytes": {
    "direct_peer": 104857600,
    "relay": 16777216,
    "cloud_egress": 0
  },
  "api_requests": 42,
  "billable": [
    {
      "meter": "relay_egress_bytes",
      "quantity": 16777216,
      "unit": "byte"
    }
  ]
}

How it works

Logical file bytes and physical transfer bytes are different. Internal retries, duplicate events, and a relay hop must not silently create duplicate billable usage. Meter definitions and prices must be published before charging customers.