Billing

The Billing API allows you to retrieve usage reports for your API key. You can use it to monitor how many requests you have made over a given time period, broken down by day or month.

Endpoint

GET /v2/billing/usage

This endpoint requires authentication via the X-API-Key header, same as all other Media API endpoints.

Query Parameters

All parameters are optional.

Parameter	Type	Default	Description
metric	string	nlp-analyze-requests	The usage metric to retrieve. Currently, only nlp-analyze-requests is supported.
granularity	string	month	The granularity of the usage data. Possible values: month, day.
sinceDate	string	see below	Start of the time range (inclusive), as an ISO date in UTC (e.g., 2025-01-01).
untilDate	string	see below	End of the time range (inclusive), as an ISO date in UTC (e.g., 2025-12-31).

Default Date Ranges

If sinceDate and untilDate are not specified, the following defaults apply:

• Monthly granularity: last 12 months up to today.
• Daily granularity: last 1 month up to today.

If only one of the two dates is provided, the other is computed automatically using the same default range (12 months for monthly, 1 month for daily granularity).

Date Constraints

• sinceDate cannot be older than 24 months from today.
• untilDate cannot be more than 12 months into the future.
• untilDate must not be before sinceDate.
• Dates must be in ISO format (YYYY-MM-DD).

Response

The response is a JSON object of type UsageResponse.

Example: Monthly Usage

GET /v2/billing/usage

{
  "metric": "nlp-analyze-requests",
  "granularity": "month",
  "sinceDate": "2025-02-05",
  "untilDate": "2026-02-05",
  "totalUsage": 102234,
  "usageByPeriod": [
    { "period": "2025-02", "usage": 4256 },
    { "period": "2025-03", "usage": 8905 },
    { "period": "2025-04", "usage": 8606 },
    { "period": "2025-05", "usage": 8929 },
    { "period": "2025-06", "usage": 8594 },
    { "period": "2025-07", "usage": 8870 },
    { "period": "2025-08", "usage": 8897 },
    { "period": "2025-09", "usage": 8602 },
    { "period": "2025-10", "usage": 8898 },
    { "period": "2025-11", "usage": 8617 },
    { "period": "2025-12", "usage": 8871 },
    { "period": "2026-01", "usage": 8883 },
    { "period": "2026-02", "usage": 1306 }
  ]
}

Example: Daily Usage

GET /v2/billing/usage?granularity=day&sinceDate=2026-01-05&untilDate=2026-02-05

{
  "metric": "nlp-analyze-requests",
  "granularity": "day",
  "sinceDate": "2026-01-05",
  "untilDate": "2026-02-05",
  "totalUsage": 9044,
  "usageByPeriod": [
    { "period": "2026-01-05", "usage": 288 },
    { "period": "2026-01-06", "usage": 282 },
    { "period": "2026-01-07", "usage": 286 },
    { "period": "2026-01-08", "usage": 286 },
    { "period": "2026-01-09", "usage": 286 },
    { "period": "2026-01-10", "usage": 286 },
    { "period": "2026-01-11", "usage": 288 },
    { "period": "2026-01-12", "usage": 286 },
    { "period": "2026-01-13", "usage": 284 },
    { "period": "2026-01-14", "usage": 286 },
    { "period": "2026-01-15", "usage": 288 },
    { "period": "2026-01-16", "usage": 290 },
    { "period": "2026-01-17", "usage": 284 },
    { "period": "2026-01-18", "usage": 284 },
    { "period": "2026-01-19", "usage": 288 },
    { "period": "2026-01-20", "usage": 286 },
    { "period": "2026-01-21", "usage": 284 },
    { "period": "2026-01-22", "usage": 286 },
    { "period": "2026-01-23", "usage": 298 },
    { "period": "2026-01-24", "usage": 284 },
    { "period": "2026-01-25", "usage": 286 },
    { "period": "2026-01-26", "usage": 290 },
    { "period": "2026-01-27", "usage": 286 },
    { "period": "2026-01-28", "usage": 278 },
    { "period": "2026-01-29", "usage": 290 },
    { "period": "2026-01-30", "usage": 288 },
    { "period": "2026-01-31", "usage": 290 },
    { "period": "2026-02-01", "usage": 284 },
    { "period": "2026-02-02", "usage": 286 },
    { "period": "2026-02-03", "usage": 286 },
    { "period": "2026-02-04", "usage": 288 },
    { "period": "2026-02-05", "usage": 162 }
  ]
}

Rate Limiting

This endpoint is rate-limited. Each API key is allowed a limited number of requests per hour. If you exceed the limit, you will receive a 429 Too Many Requests response.

Error Responses

Status Code	Description
400	Invalid request parameters (e.g., invalid date format, invalid date range).
429	Rate limit exceeded. Try again later.
500	Internal server error (e.g., upstream service unavailable).