# 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](https://www.infobip.com/docs/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](https://www.infobip.com/docs/essentials/api-essentials/api-authorization#api-scopes).
- **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.

NOTE
Requests missing `dateInterval` or `aggregateBy` return a validation error. The date range must not exceed 3 months.

### Example [#example]

```json
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]

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

| Filter | Description | Notes |
| --- | --- | --- |
| `dateInterval` | Time period for billing data in UTC | Required. Uses `sentSince` and `sentUntil` in `yyyy-MM-dd` format. Max range: current month and two months prior. |
| `categories` | Channel or service to filter by | See [Categories](https://www.infobip.com/docs/billing-usage-api/billing-data-reference#categories). |
| `trafficTypes` | Traffic type within a channel | Values vary by channel. |
| `platforms` | CPaaS X application and entity combination | Use to isolate costs per tenant or use case. |
| `campaignReferenceIds` | Campaign reference ID | Available in the API only, not in financial reports. |
| `countryCodes` | Destination countries | ISO 3166-1 alpha-2 format (for example, `["US", "DE"]`). |
| `accountKeys`, `senders`, `senderTypes`, `directions`, `subCategories`, `campaignIds`, `templateIds` | Additional optional filters | See the [Billing data reference](https://www.infobip.com/docs/billing-usage-api/billing-data-reference) for valid values. |

NOTE
In the US, SMS and MMS traffic generates a separate `SMS_OPERATOR_FEE` or `MMS_OPERATOR_FEE` category for carrier surcharges. To capture the full cost, include both in your filter: `categories: ["SMS", "SMS_OPERATOR_FEE"]`.

### Options [#options]

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

```json
"options": {
  "includeUnfinalizedData": false
}
```

### Aggregation dimensions [#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:

| If you send... | Result includes... |
| --- | --- |
| `["DAY"]` | `ACCOUNT_NAME`, `CATEGORY_CODE`, `DAY` |
| `["ACCOUNT_KEY", "DAY"]` | `CATEGORY_CODE`, `ACCOUNT_KEY`, `DAY` |
| `["ACCOUNT_NAME", "CATEGORY_NAME", "DAY"]` | `ACCOUNT_NAME`, `CATEGORY_NAME`, `DAY` |
| `["ACCOUNT_KEY", "CATEGORY_NAME", "DAY"]` | `ACCOUNT_KEY`, `CATEGORY_NAME`, `DAY` |

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.

For the full list of `aggregateBy` enum values and their definitions, see [Dimensions](https://www.infobip.com/docs/billing-usage-api/billing-data-reference#dimensions) in the Billing data reference.

___

## 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.

NOTE
The `requestedPeriod` in the response may differ from your requested date range. The range may be aligned to the aggregation granularity and, where applicable, trimmed to finalized periods only.

For cost field definitions and currency format, see [Cost fields](https://www.infobip.com/docs/billing-usage-api/billing-data-reference#cost-fields).

___

Related pages

[Billing data reference](https://www.infobip.com/docs/billing-usage-api/billing-data-reference)
Look up all valid categories, traffic types, and aggregation dimension codes.

[Financial reports](https://www.infobip.com/docs/analyze/reports/financial/understand-financial-reports)
View the same billing data through the web interface with scheduling and export options.