Querying data

The Metrics API provides a straightforward way to query and retrieve data related to traffic across your services. You can integrate it seamlessly into your systems to gain insights into various aspects of your activities.

Asynchronous analytics query

Submit the query

You must send a POST request to the Metrics API. This API tells Infobip to process your request in the background. If the query submission succeeds, the API returns a 201 status and a requestID that you will use to refer to the query in later steps.

For example:

json

 
{
  "callbackUrl": "{https://example.com/receive}",
  "request": {
    "filterBy": {
      "accountKeys": [
        "{AccountKeys}"
      ],
      "sentSince": "2024-04-01T00:00:00.000+0000",
      "sentUntil": "2024-04-01T01:00:00.000+0000",
      "includeSubaccounts": true,
      "directions": [
        "OUTBOUND"
      ],
      "channelCodes": [
        "SMS"
      ]
    },
    "aggregateBy": [
      "ACCOUNT_KEY",
      "HOUR",
      "DIRECTION",
      "STATUS"
    ],
    "metrics": [
      "TOTAL_TRAFFIC_COUNT",
      "DELIVERED_TRAFFIC_COUNT"
    ]
  }
}

You can specify the callback URL parameter on the request (using the callbackUrl parameter) to determine where the processed query results should be delivered, streamlining your workflow.

Get query status

Send a GET request to the Metrics API to request the status of the query. You need to provide the request ID that the POST call returned.

For example:

json

 
curl -L -g 'https://{baseUrl}/metrics/1/requests/{requestId}' \
-H 'Authorization: {authorization}' \
-H 'Accept: application/json'

Request body

This section describes each parameter you can use in the JSON request body for a query. For details on metrics and dimensions that you can use in your query, see Metrics and filters.

Property	Description	Required
filter by	Dimensions that can be used to filter data. Filters can be combined. For more information, see the list of filtering parameters.	Yes
aggregate by	Array of dimensions to group the metrics. For more information, see the list of supported dimensions. You can specify multiple dimensions.	Yes
metrics	You can specify one or more metrics for a query where each metric includes only the metric name.	Yes

Constraints

Note

During the early access phase, Metrics API is not deployed and available across all Data Centers (DCs), and limitations per region may apply. If you encounter any issues or have questions regarding API access in your region, reach out to our support (opens in a new tab).

Legacy accounts

Metrics API may not be available for legacy account setups. If you encounter difficulties accessing this feature, contact support (opens in a new tab) for assistance.

Time range querying

The Metrics API allows you to retrieve aggregated data over various time granulations. The available granulations and their constraints based on the requested range of days are as follows:

Allowed granulations:

HOUR
DAY
WEEK_SUNDAY
WEEK_MONDAY
WEEK_SATURDAY
MONTH
QUARTER
YEAR

Depending on the requested range of days, not all granulations are allowed. The constraints are outlined below:

Granulation	Maximum range	Example
Hour	14 days	If you request data from 2023-05-01 to 2023-05-14, you can use `HOUR` granulation.
Day	93 days	If you request data from 2023-02-01 to 2023-05-05, you can use `DAY` granulation.
Week and Month	371 days	If you request data from 2022-06-01 to 2023-06-06, you can use `WEEK_SUNDAY`, `WEEK_MONDAY`, `WEEK_SATURDAY`, or `MONTH` granulation.
Quarter and Year	1100 days	If you request data from 2021-01-01 to 2024-01-05, you can use `QUARTER` or `YEAR` granulation.

Overview Metrics and filters