Skip to content

docs(reporting-api): clarify to semantics, used_bytes units, and data freshness #62

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
oreoluwadnd wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(reporting-api): clarify to semantics, used_bytes units, and data freshness #62

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 11 additions & 4 deletions reporting-api-reference/Massive-Proxy-Reporting-API-v1.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ paths:
Get usage data for the given time range.

If no time range is provided, returns usage for the past 7 days (including today).

Usage is aggregated hourly — see [Data freshness](/reporting-api-reference/reporting-api#data-freshness) before scheduling reporting jobs.
operationId: getUsage
security:
- ApiKeyAuth: []
Expand All @@ -39,11 +41,13 @@ paths:
type: string
required: false
description: |
End data to query usage (UTC).
End date/time to query usage (UTC).

Accepted formats: date (`2025-01-01`) or RFC3339 (`2025-01-01T10:00:00Z`).

Must be greater than 'from' date.
Must be greater than 'from'.

@jemxz jemxz Jul 27, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must be greater than from is not very understandable


Accepted formats: date, RFC3339.
Usage is aggregated in hourly buckets, and the range **includes the hourly bucket containing** `to`. A date-only value is interpreted as midnight UTC (00:00:00), so it returns only the first hour of that day — to include a full final day, pass `to=YYYY-MM-DDT23:59:59Z`.
example: "2025-01-01 or 2025-01-01T10:00:00Z"
responses:
"200":
Expand Down Expand Up @@ -85,7 +89,10 @@ components:
example: 500
used_bytes:
type: number
description: The number of used bytes
description: |
Bytes consumed (raw bytes).

To convert to GB as shown in the dashboard, divide by 10⁹ (decimal GB, not 2³⁰).
example: 123456789
Error:
type: object
Expand Down
8 changes: 8 additions & 0 deletions reporting-api-reference/reporting-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,11 @@ curl --location 'https://api-network.joinmassive.com/reporting/v1/usage' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {PROXY_PASSWORD}'
```

# Data freshness

Usage data is aggregated hourly, a few minutes after each hour completes. A calendar day (UTC) is final approximately 15 minutes after midnight UTC, once its last hour is aggregated. For daily reporting jobs, query after 00:30 UTC with `to=YYYY-MM-DDT23:59:59Z`.

<Note>
Usage is recorded when a connection closes, so a session that crosses midnight counts toward the day in which it ends.
</Note>