Metrics

This endpoint lets you get general metrics for your keyset or account, specifying the timeline for those metrics and how they should be grouped.

To read about the available metrics, categories, and their limitations, refer to the general Insights API documentation.

Query Parameters
`entityType` string — REQUIRED Possible values: [`account`, `keyset`] Type of entity you are requesting information for.
`entityId` string — REQUIRED Alphanumeric ID of the entity for which you are requesting information. For entityType=keyset, this is the subscribe key from the Keyset view in the Admin Portal (e.g. `sub-c-4240e3e3-0e27-4e19-9c06-370935ca282d`). For entityType=account, this is the account ID from the URL in the Admin Portal (e.g. `180404`).
`fromDate` string — REQUIRED Start of the date range for which you want the metrics (YYYY-MM-DD).
`toDate` string — REQUIRED End of the date range for which you want the metrics (YYYY-MM-DD).
`period` string — REQUIRED Possible values: [`hourly`, `daily`, `weekly`, `monthly`] Aggregation of the returned metrics.
`metric` string[] — REQUIRED Possible values: [`message_by_country`, `unique_users_by_country`, `unique_channels`, `percent_unique_channels_with_messages`, `unique_channels_combination`, `unique_users`, `percent_unique_users_with_messages`, `unique_users_combination`, `new_vs_recurring_users`, `messages`, `top_10_message_types`] Metric you are requesting data for (one or many). Names are case-sensitive.

Header Parameters
`X-Session-Token` string — REQUIRED Authentication header

Responses

200

Even if the status code is 200 (success), sometimes you might not see anything returned in dataResult. This can happen when the data you requested is not available at the moment. In such cases, try again later.

Schema — OPTIONAL

metrics object

Information about the selected metrics. It is a key-value property where the key is the name of the metric.

status string

Status of the given metric.

reason string — OPTIONAL

Reason why the data isn't returned. Available only when the status is failed.

code number

Status code of the metric.

dataResult object

Data for the selected queries. It is a key-value property where the key is the name of the metric.

inputEcho object

Data provided by the user in the API request.

entityType string

Possible values: [account, keyset]

entityId string

fromDate string

toDate string

period string

Possible values: [hourly, daily, weekly, monthly]

metric string[]

Possible values: [message_by_country, unique_users_by_country, unique_channels, percent_unique_channels_with_messages, unique_channels_combination, unique_users, percent_unique_users_with_messages, unique_users_combination, new_vs_recurring_users, messages, top_10_message_types]

400

For example, you can get this error if the period you provided is invalid for the requested metric. In such cases, use a different period to request the metric.

Schema — OPTIONAL
`statusCode` number
`message` string[]
`error` string

401

This error occurs when you are not authenticated (you didn’t provide the token in the header of an API call).

Schema — OPTIONAL
`statusCode` number
`message` string

403

This is a Forbidden resource error.
1) It can occur if your account only has the Insights Standard version activated but does not have Insights Premium. The Insights API is only available to Insights Premium users.
2) This might also occur when you are requesting data for an account / keyset that you don’t have access to.

Schema — OPTIONAL
`statusCode` number
`message` string
`error` string

500

This is a server error (Bad Request). This would usually mean something has gone wrong on PubNub’s end, for example, when the database is down. If you see this error and cannot find the reason for it, contact PubNub support.