Query billing data

This guide walks you through building a billing usage query, from setting filters and aggregation dimensions to handling the callback response.

For an overview of the API, supported channels, and data finalization behavior, see Billing Usage API.

Before you begin

Make sure you have the following before sending your first request:

• API key: Must have the billing:usage:view scope. A 401 Unauthorized error means this scope is missing. See API authorization.
• Callback URL: A publicly reachable endpoint on your server where Infobip POSTs results (localhost will not work). If results are not arriving, check firewall rules and confirm the request was accepted by checking the requestId in the initial response.
• Date range: Data is available for the current month and the previous two calendar months only.

Build your request

Every request requires three fields: callbackUrl, filterBy.dateInterval, and at least one entry in aggregateBy. All other filters are optional.

Example

POST /billing/1/usage/query
 
{
  "callbackUrl": "https://your-server.com/billing-callback",
  "request": {
    "filterBy": {
      "dateInterval": {
        "sentSince": "2026-04-01",
        "sentUntil": "2026-04-30"
      }
    },
    "aggregateBy": ["DAY"]
  }
}

This returns costs for April 2026 broken down by day. ACCOUNT_NAME and CATEGORY_CODE are added automatically as defaults since no account or category dimension is specified.

Filters

Filters narrow which data is included before processing. dateInterval is required. All others are optional.

Options

• includeUnfinalizedData (boolean, default true): Set to false to return only finalized billing periods and exclude current-month provisional data.

"options": {
  "includeUnfinalizedData": false
}

Aggregation dimensions

Aggregation dimensions define how results are grouped in the response. Filters narrow which data is included; dimensions define how it is grouped. For example, filtering by categories: ["SMS"] limits results to SMS; adding "COUNTRY_NAME" to aggregateBy then breaks that down by country.

At least one dimension is required in aggregateBy. Two pairs have auto-added defaults if you don't specify either variant from the pair:

Default auto-added dimensions:

• ACCOUNT_NAME is auto-added if neither ACCOUNT_NAME nor ACCOUNT_KEY is specified.
• CATEGORY_CODE is auto-added if neither CATEGORY_CODE nor CATEGORY_NAME is specified.

Specifying one variant suppresses the other; both are never added simultaneously unless you explicitly include both.

Additional dimensions cover time (DAY, MONTH), geography (COUNTRY_NAME, NETWORK_NAME), sender, campaign, and multitenant context (APPLICATION_ID, ENTITY_ID). Campaign and template dimensions return IDs only. Names are not included in billing data.

Response data

Results are delivered to your callback URL as JSON. The response includes:

• requestId: Matches the ID returned when you submitted the query.
• status: SUCCESS or FAILED.
• response: Present when status is SUCCESS. Contains requestedPeriod, totalRows, columns, and rows.
• failureMessage: Present when status is FAILED.
• metadata: Present on success. Contains clientRequestedPeriod and billingPeriods.

The response.rows array contains one entry per aggregation combination. Each row maps values to the columns array by index. If a metric is not available for a given channel, the corresponding value is "N/A".

The metadata.billingPeriods array indicates the finalization status of each calendar month covered by your query. volumeFinalized: true means billing data for that month has been fully processed and no further volume changes are expected. Always verify final amounts against your invoice.

For cost field definitions and currency format, see Cost fields.