Skip to content
Pomelo Analytics

Usage history by month

GET
/v1/usage/history

Requires usage:read scope. Tokens with metrics:read also have implicit access to this endpoint.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters ”
X-Request-Id
string

Optional idempotency/request correlation identifier.

Query Parameters

Section titled “Query Parameters ”
from
string format: date

Inclusive UTC start date (YYYY-MM-DD). Defaults to last 7 days.

to
string format: date

Inclusive UTC end date (YYYY-MM-DD). Defaults to today.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

OK

object
items
required
Array<object>
object
period
required
string
Example
2026-01
units_used
required
integer
units_included
required
integer
units_overage
required
integer
hard_cap_units
required
integer

Headers

Section titled “Headers ”
X-Request-Id
string

Request identifier for troubleshooting.

401

Section titled “401 ”

Invalid or revoked API token.

object
error
required
object
code
required
string
Allowed values: UNAUTHORIZED FORBIDDEN INVALID_METHOD INVALID_PARAMS RETENTION_EXCEEDED RATE_LIMITED HARD_CAP_REACHED REPORT_LOCKED_BY_PROFILE REPORT_NOT_AVAILABLE_FOR_REQUESTED_PERIOD REPORT_RESPONSE_TOO_LARGE INTERNAL_ERROR NOT_FOUND
message
required
string
request_id
required
string
details
object
key
additional properties
any

Headers

Section titled “Headers ”
X-Request-Id
string

Request identifier for troubleshooting.

403

Section titled “403 ”

Token scope/site/plan does not allow this request.

object
error
required
object
code
required
string
Allowed values: UNAUTHORIZED FORBIDDEN INVALID_METHOD INVALID_PARAMS RETENTION_EXCEEDED RATE_LIMITED HARD_CAP_REACHED REPORT_LOCKED_BY_PROFILE REPORT_NOT_AVAILABLE_FOR_REQUESTED_PERIOD REPORT_RESPONSE_TOO_LARGE INTERNAL_ERROR NOT_FOUND
message
required
string
request_id
required
string
details
object
key
additional properties
any

Headers

Section titled “Headers ”
X-Request-Id
string

Request identifier for troubleshooting.

422

Section titled “422 ”

Request parameters are invalid.

object
error
required
object
code
required
string
Allowed values: UNAUTHORIZED FORBIDDEN INVALID_METHOD INVALID_PARAMS RETENTION_EXCEEDED RATE_LIMITED HARD_CAP_REACHED REPORT_LOCKED_BY_PROFILE REPORT_NOT_AVAILABLE_FOR_REQUESTED_PERIOD REPORT_RESPONSE_TOO_LARGE INTERNAL_ERROR NOT_FOUND
message
required
string
request_id
required
string
details
object
key
additional properties
any

Headers

Section titled “Headers ”
X-Request-Id
string

Request identifier for troubleshooting.

429

Section titled “429 ”

Request was throttled.

object
error
required
object
code
required
string
Allowed values: UNAUTHORIZED FORBIDDEN INVALID_METHOD INVALID_PARAMS RETENTION_EXCEEDED RATE_LIMITED HARD_CAP_REACHED REPORT_LOCKED_BY_PROFILE REPORT_NOT_AVAILABLE_FOR_REQUESTED_PERIOD REPORT_RESPONSE_TOO_LARGE INTERNAL_ERROR NOT_FOUND
message
required
string
request_id
required
string
details
object
key
additional properties
any

Headers

Section titled “Headers ”
X-Request-Id
string

Request identifier for troubleshooting.

X-RateLimit-Limit
integer

Maximum requests allowed during current short window.

X-RateLimit-Remaining
integer

Remaining requests in current short window.

X-RateLimit-Reset
integer

Unix timestamp when short window resets.