Top metrics

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

To read about the available top metrics, categories, and their limitations, refer to the general Insights API documentation. Example cURL command:

curl --location --globoff 'https://admin.pubnub.com/api/insights/top?entityType=keyset&entityId=your-subscribe-key&fromDate=YYYY-MM-DD&toDate=YYYY-MM-DD&period=daily&metric[]=top_20_channels' \ --header 'X-Session-Token: <PASTE TOKEN HERE>'

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]

Aggregation of the returned metrics.

metric[] string[] — REQUIRED

Possible values: [top_20_channels, top_1000_channels, top_20_users, top_1000_users, top_20_channels_with_user_duration, top_1000_channels_with_user_duration]

Top metric you request data for (one or many). Names are case-sensitive.

category string — REQUIRED

Possible values: [all, by_chats, by_messages, by_subscribers, by_users_with_chats, by_users_with_messages, by_subscribed_channels]

You must provide one of the listed categories when requesting (one or many) top metrics. Names are case-sensitive.

filters object

You can use this parameter to filter results:

  • For specified channel(s) / user(s).
  • Based on specified conditions.

Possible operators: [eq, neq, gt, lt, gte, lte, in, nin, startsWith]

Example filters:

  {
    "top_1000_channels": [
      {
        "field": "channel_name",
        "operator": "in",
        "value": ["channel-1","channel-2"]
      }
    ]
  }
  {
    "top_1000_users": [
      {
        "field": "uuid",
        "operator": "in",
        "value": ["user-1","user-2"]
      }
    ]
  }
   {
    "top_1000_channels": [
      {
        "field": "count_messages",
        "operator": "gt",
        "value": "1"
      }, 
      {
        "field": "count_subscribers",
        "operator": "eq",
        "value":"2"
      }
    ]
  }
  {
    "top_1000_channels": [
      {
        "field": "channel_name",
        "operator": "startsWith",
        "value": "3d2f"
      }
    ], 
    "top_1000_users": [
      {
        "field": "uuid",
        "operator": "in",
        "value": ["user-1","user-2"]
      }
    ]
show all 16 lines
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.