docs(reporting-api): clarify to semantics, used_bytes units, and data freshness - #62
Open
oreoluwadnd wants to merge 1 commit into
Open
docs(reporting-api): clarify to semantics, used_bytes units, and data freshness#62oreoluwadnd wants to merge 1 commit into
to semantics, used_bytes units, and data freshness#62oreoluwadnd wants to merge 1 commit into
Conversation
…reshness Closes three gaps reported by customers against /v1/usage (SUP-1368, origin SUP-1308): - `to` is inclusive of the hourly bucket containing it, and a date-only value means midnight UTC — so it returns only the first hour of that day. Document passing `to=YYYY-MM-DDT23:59:59Z` for a full final day. - `used_bytes` is raw bytes; divide by 10^9 for the decimal GB shown in the dashboard. - Add a "Data freshness" section covering hourly aggregation, when a UTC day is final, and that usage is recorded when a connection closes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
oreoluwadnd
force-pushed
the
docs/sup-1368-reporting-api-semantics
branch
from
July 26, 2026 22:11
cdb4daf to
dd0bb11
Compare
jemxz
reviewed
Jul 27, 2026
| Accepted formats: date (`2025-01-01`) or RFC3339 (`2025-01-01T10:00:00Z`). | ||
|
|
||
| Must be greater than 'from' date. | ||
| Must be greater than 'from'. |
Collaborator
There was a problem hiding this comment.
Must be greater than from is not very understandable
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes the three Reporting API documentation gaps confirmed in SUP-1368 (origin: SUP-1308, Datamam). Wording is the engineering-verified text from the issue.
Changes
toparameter (Get usage) — documents that the range includes the hourly bucket containingto, and that a date-only value means midnight UTC, so it returns only the first hour of that day. Points atto=YYYY-MM-DDT23:59:59Zfor a full final day. Also fixes the pre-existing "End data to query usage" typo.used_bytesfield — raw bytes; divide by 10⁹ for the decimal GB shown in the dashboard.New "Data freshness" section (Reporting API overview) — hourly aggregation, a UTC day being final ~15 min after midnight, guidance to run daily jobs after 00:30 UTC, and the caveat that usage is recorded on connection close so midnight-crossing sessions count toward the day they end in.
The freshness note lives on the overview page because the Get usage page is generated entirely from the OpenAPI spec and has no body content; the endpoint description links to it.
Note
If PROXY-402 (date-only
to→ end of day) ships, thetodescription will need a small revision — this documents current behavior.🤖 Generated with Claude Code