Get company API usage
Retrieve bounded API usage, protected-content delivery counts, and current quota status for the represented Company.
GET/v1/company/usage
Request schema: None
Success schema: CompanyUsageResponseV1
Documented HTTP statuses: 200, 400, 401, 403, 404, 503
Contract: company-context-v1.openapi.json
Authorization
The Company is derived from the authenticated caller context. Partner-application requests report usage only for the represented Company and, where policy requires it, only for the calling application.
Request guidance
Optionally send from and through as inclusive UTC dates. The default period is the most recent 30 days and the maximum period is 90 days. No org_id parameter is accepted.
Parameters
| Name | In | Type | Presence | Constraints | Description |
|---|---|---|---|---|---|
from | query | string (date) | Optional | First UTC usage date. Defaults to 29 days before through. | |
through | query | string (date) | Optional | Last inclusive UTC usage date. Defaults to the current UTC date. |
Request body
This operation has no JSON request body.
Idempotency and recovery
No idempotency key is used because this operation is read-only.
Response guidance
Business usage is separate from HTTP request telemetry. data_through states how current the figures are. The active_catalog_items quota may be displayed with its measured_at timestamp as measured catalog capacity.
Synthetic success example: Usage and quota status
{
"contract_version": "v1",
"evaluated_at": "2026-10-29T16:00:00Z",
"data_through": "2026-10-29T15:55:00Z",
"period": {
"from": "2026-10-01",
"through": "2026-10-29",
"timezone": "UTC"
},
"api_usage": {
"summary": {
"request_count": 125,
"successful_request_count": 120,
"denied_request_count": 3,
"failed_request_count": 2,
"submitted_item_count": 40,
"returned_item_count": 310
},
"protected_content": {
"hph_item_codes_delivered": 200,
"unique_hph_item_codes_delivered": 75,
"hph_item_codes_withheld": 15,
"quota_denied_request_count": 1
},
"daily": [
{
"date": "2026-10-29",
"request_count": 12,
"returned_item_count": 30,
"hph_item_codes_delivered": 20,
"unique_hph_item_codes_delivered": 8
}
]
},
"quotas": [
{
"quota": "daily_returned_items",
"maximum": 1000,
"consumed": 310,
"reserved": 10,
"remaining": 680,
"resets_at": "2026-10-30T00:00:00Z",
"measured_at": null
},
{
"quota": "active_catalog_items",
"maximum": 50000,
"consumed": 12000,
"reserved": null,
"remaining": 38000,
"resets_at": null,
"measured_at": "2026-10-29T15:45:00Z"
}
]
}