--- title: "Query billing usage data" method: POST path: "/billing/1/usage/query" tags: ["platform", "billing-usage-api"] --- # Query billing usage data `POST /billing/1/usage/query` ## Request - Base URL: `https://api.infobip.com` (the document declares no server; this is the origin it was published from) - URL: `https://api.infobip.com/billing/1/usage/query` - Auth: one of: - OAuth 2 - Client credentials - Token URL: `https://api.infobip.com/auth/1/oauth2/token` - API key in header `Authorization` - API key in header `Authorization` - HTTP basic Start the process of aggregating billing-grade financial cost data for your Infobip traffic. The results are delivered once via POST to the `callbackURL` provided in the request. Make sure the URL is reachable before submitting. See [Receive billing usage result](#platform/billing-usage-api/receive-billing-usage-result) for the webhook payload structure. ## Request body - 99c561addf74bb07fd67942658f68818323ce564cc5eef645d487517ca1425f2QueryBillingUsageRequest - `callbackUrl` string, required: Target URL to receive the query processing results. For schema details, see: [Receive billing usage result](#platform/billing-usage-api/receive-billing-usage-result). - `request` 99c561addf74bb07fd67942658f68818323ce564cc5eef645d487517ca1425f2QueryBillingUsageApiRequest, required: Contains filter criteria, aggregation dimensions, and query options for the billing usage report. - `filterBy` 99c561addf74bb07fd67942658f68818323ce564cc5eef645d487517ca1425f2BillingUsageDataFilter, required: A JSON object specifying criteria to filter the results. Each field in the object represents a different filter criterion to enable detailed and complex filtering. - `dateInterval` 99c561addf74bb07fd67942658f68818323ce564cc5eef645d487517ca1425f2DateInterval, required: Time period for billing data in UTC. sentSince is inclusive and sentUntil is exclusive. - `sentSince` string, date, required: Start of period (inclusive). Uses UTC timezone. Format: `yyyy-MM-dd`. - `sentUntil` string, date, required: End of period (exclusive). Uses UTC timezone. Format: `yyyy-MM-dd`. - `accountKeys` string[]: Specifies a list of unique account keys (identifiers). If not provided, data for all accounts in the customer hierarchy will be included. To retrieve all available account keys, refer to the [Account list endpoint](https://www.infobip.com/docs/api/platform/account-management/get-all-accounts). - `categories` string[]: Channel or service categories to filter by. If not provided, all billing categories available to the authenticated account are included. - `subCategories` string[]: Subcategories of categories (service variants). Applicable to Viber, Voice and Video and Kakao. - `countryCodes` string[]: Specifies ISO 3166-1 alpha-2 country codes to filter billing data for specific countries. - `platforms` 99c561addf74bb07fd67942658f68818323ce564cc5eef645d487517ca1425f2Platform[]: Specifies the platform object, which is a combination of an applicationId and entityId. These IDs uniquely identify each application and entity configured on the Infobip platform. Use this object and its related parameters to filter data for a specific application and entity combination. Note that these parameters should only be used if you leverage CPaaS X applications and entities to manage your traffic. For detailed information on applications and entities in the CPaaS X ecosystem, refer to the [CPaaSX overview](https://www.infobip.com/docs/cpaas-x/application-and-entity-management). - `applicationId` string: A unique identifier assigned to an application, use case, or environment within the Infobip CPaaS X ecosystem. Use this parameter to filter data for a specific application. To retrieve all available application IDs, refer to the [Application list endpoint](https://www.infobip.com/docs/api/platform/application-entity/get-applications). - `entityId` string: A unique identifier assigned to an entity, such as a brand, customer, or other defined component, within the Infobip CPaaS X ecosystem. Use this parameter to filter data for a specific entity. To retrieve all available entity IDs, refer to the [Entity list endpoint](https://www.infobip.com/docs/api/platform/application-entity/get-entities). - `directions` 99c561addf74bb07fd67942658f68818323ce564cc5eef645d487517ca1425f2Direction[]: Specifies the direction of traffic, indicating whether the message was sent to the user (OUTBOUND) or received from the user (INBOUND). - `trafficTypes` string[]: Specifies the types of traffic. For a full list of values, refer to [traffic types](https://www.infobip.com/docs/reporting/metrics-reference/billing-data-reference#traffic-types-by-channel). - `senders` string[]: Specifies the sender IDs, which can be alphanumeric or numeric. - `senderTypes` string[]: Specifies the types of senders. For a full list of values, refer to [sender types](https://www.infobip.com/docs/reporting/metrics-reference/messaging-metrics-reference#sender-types). - `campaignReferenceIds` string[]: Specifies the list of campaign reference IDs used for traffic sent over Infobip APIs. Use `campaignReferenceIds` to filter data related to specific campaigns. - `campaignIds` integer[]: Campaign IDs, also known as communication IDs, associated with Broadcast or Moments/Flow campaigns. Use these values to filter billing data related to specific campaigns. For detailed information on the differences between Broadcast and Flow campaigns, refer to the [Broadcast](https://www.infobip.com/docs/broadcast) and [Flow overview](https://www.infobip.com/docs/moments). - `templateIds` string[]: WhatsApp template IDs. - `aggregateBy` 99c561addf74bb07fd67942658f68818323ce564cc5eef645d487517ca1425f2BillingUsageAggregate[]: An array of strings that defines the properties used for data aggregation. Each item in the array represents an aggregation parameter, with a corresponding column in the response showing values for the chosen aggregate. If neither `ACCOUNT_NAME` nor `ACCOUNT_KEY` is specified, `ACCOUNT_NAME` is prepended to the response columns automatically. If neither `CATEGORY_NAME` nor `CATEGORY_CODE` is specified, `CATEGORY_CODE` is prepended to the response columns automatically. Available aggregation dimensions: **Time:** * `DAY` - Day-level aggregation * `MONTH` - Month-level aggregation **CPaaSX Context:** * `APPLICATION_ID` - CPaaSX application identifier * `ENTITY_ID` - CPaaSX entity identifier **Account:** * `ACCOUNT_NAME` - Account display name * `ACCOUNT_KEY` - Account identifier * `USER_NAME` - User who initiated traffic **Service:** * `CATEGORY_NAME` - Channel/service display name * `CATEGORY_CODE` - Channel/service code * `SUBCATEGORY_NAME` - Service variant name * `SUBCATEGORY_CODE` - Service variant code * `DIRECTION` - Inbound/Outbound * `TRAFFIC_TYPE` - Channel-specific classification **Sender:** * `SENDER` - Sender ID/number/domain * `SENDER_TYPE` - VLN, shortcode, alphanumeric **Geography:** * `NETWORK_NAME` - Mobile operator name * `NORM_NET_CODE` - MCC+MNC code * `COUNTRY_NAME` - Destination country * `COUNTRY_CODE` - ISO 3166-1 alpha-2 code * `COUNTRY_PREFIX` - International dialing code **Campaign:** * `CAMPAIGN_ID` - Campaign identifier * `CAMPAIGN_REFERENCE` - External campaign reference * `TEMPLATE_ID` - WhatsApp template ID - `options` 99c561addf74bb07fd67942658f68818323ce564cc5eef645d487517ca1425f2BillingUsageQueryOptions: Settings controlling data completeness, including whether unfinalized billing data is included. - `includeUnfinalizedData` boolean: Controls whether to include billing data where volumes have not yet been finalized. Set to `true` to include the latest unfinalized data, or `false` to return only finalized billing data. ## Response `201` Data querying process is started. - 99c561addf74bb07fd67942658f68818323ce564cc5eef645d487517ca1425f2QueryAggregateDataResponse - `requestId` string, required: The identifier of the submitted request. ## Other responses - `400`: Request is malformed or invalid. - `401`: Unauthorized - `403`: Forbidden - `429`: Too Many Requests - `500`: Internal Server Error --- [API](https://skmtc.dev/infobip/apis/infobip-openapi-specification.md) - [All operations](https://skmtc.dev/infobip/apis/infobip-openapi-specification/llms.txt) - [OpenAPI document](https://skmtc.dev/infobip/apis/infobip-openapi-specification/revisions/9dcbbaf902de?raw)