Get advanced analytics metrics

Retrieves advanced analytics metrics based on the specified parameters. You can retrieve either daily or monthly metrics using the time_dimension parameter.

Note: Daily metrics are calculated and updated every three hours, starting at 1 a.m. in UTC. Meanwhile, monthly metrics are calculated after the last day of the month.

HTTP request

GET https://api-{application_id}.sendbird.com/v3/statistics/metric

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
metric_type	string	Specifies a metric to retrieve, in accordance with the required and optional parameters. Acceptable values are the following: - messages: the total number of sent messages. - messages_per_user: the average number of sent messages per user. - created_channels: the total number of new channels. - active_channels: the total number of channels where at least one message has been sent. - message_senders: the total number of users that have sent at least one message. - message_viewers: the total number of users who have viewed at least one message. The value is deduplicated based on the user ID. - created_users: the total number of new users. - deactivated_users: the total number of users who were deactivated and denied access to your Sendbird application. - deleted_users: the total number of deleted users.
time_dimension	string	Specifies the time range of the metric. Acceptable values are daily and monthly. For both daily and monthly metrics, `time_dimension` should be specified in conjunction with the `start_year`, `end_year`, `start_month`, and `end_month`. However, when the value is daily, `start_day` and `end_day` should be specified as well. * A value of monthly is only effective when the value of `metric_type` is either message_senders or active_channels.
start_year	int	Specifies the start year of the metric's time range, in YYYY format.
end_year	int	Specifies the end year of the metric's time range, in YYYY format.
start_month	int	Specifies the start month of the metric's time range as an integer from 1 to 12, inclusive.
end_month	int	Specifies the end month of the metric's time range as an integer from 1 to 12, inclusive.

Optional	Type	Description
limit	int	Specifies the number of results to return per page. Acceptable values range from 1 to 1,000, inclusive. (Default: 1,000)
token	string	Specifies a page token that indicates the starting index of a chunk of results to retrieve. If not specified, the index is set as 0.
segments	string	Specifies by what groups to divide the metrics. Acceptable values are channel_type, custom_channel_type, and custom_message_type. These values are effective only when the `metric_type` parameter is set to either messages or created_channels. Supported segments for the messages and created_channels metrics are the following: - messages: channel_type, custom_channel_type, custom_message_type, or a combination of custom_channel_type and custom_message_type - created_channels: custom_channel_type When `metric_type` is set to messages, the retrieved data is segmented either by one of the three acceptable values or as a combination of custom_channel_type and custom_message_type. To retrieve metrics as a combination of segments, the value of `segments` should be specified in the order of custom_channel_type and custom_message_type. * If more than 400 segments exist within the specified `time_dimension`, this action doesn't provide the segmentation breakdown for the metric. On the other hand, if channel_type, custom_channel_type, or custom_message_type has a value of null, the result covers the entire scope without being limited by channel or message types.
start_day	int	Specifies the start day of the metric's time range as an integer from 1 to 31, inclusive. This parameter should be specified in conjunction with the `time_dimension` and is required when the `time_dimension` is daily.
end_day	int	Specifies the end day of the metric's time range as an integer from 1 to 31, inclusive. This parameter should be specified in conjunction with the `time_dimension` and is required when the `time_dimension` is daily.
export_as_csv	boolean	Determines whether to export the metric as a CSV file instead of including it in the response. If set to true, the response includes the URL to download the exported file. (Default: false)

Query string example

?metric_type=messages&start_year=2020&end_year=2020&time_dimension=daily

Response

If successful, this action returns a list of an advanced analytics data in the response body.

Note: If the number of custom channel types or custom message types exceeds 400, this action returns only values whose custom_channel_type or custom_message_type has a value of null.

Also when the export_as_csv parameter is set to true, the response body includes an URL for the file. Meanwhile, specifying segments for the other seven metrics may return an error.

Status: 200 OKWhen custom types exceed 400When exporting a CSV file

{
    "metric_type": "messages",
    "segments": [
        "custom_channel_type"
    ],
    "values": [
        {
            "date": "2020-03-22",
            "custom_channel_type": "Book club",
            "value": 56
        },
        {
            "date": "2020-03-22",
            "custom_channel_type": null,
            "value": 399
        },
        {
            "date": "2020-03-23",
            "custom_channel_type": "Baking class",
            "value": 87
        },
        {
            "date": "2020-03-23",
            "custom_channel_type": null,
            "value": 292
        }
    ],
    "next": "pNsRScFRrZaIEERRx1RcE2d0FUZSUlkJFVQRHB86AkAgNn8eAERrD11..."
}

When metric_type is messages and segments is channel_type, the values include information on which channel type the data belongs to.

Status: 200 OK

{
    "metric_type": "messages",
    "segments": [
        "channel_type"
    ],
    "values": [
        {
            "date": "2020-03-22",
            "channel_type": "Open channel",
            "value": 399
        },
        {
            "date": "2020-03-23",
            "channel_type":"Private group channel",
            "value": 292
        }
    ]
    "next": "pNsRScFRrZaIEERRx1RcE2d0FUZSUlkJFVQRHB86AkAgNn8eAERrD11..."
}

List of response properties

Property name	Type	Description
metric_type	string	The retrieved metric.
segments	array	The array of one or more data types that are retrieved on the metrics.
values	list	The list of Advanced analytics data that match the specified parameters.
next	string	The value that can be used in the `token` parameter to retrieve the next page in the result set.

In the case of an error, an error object is returned. A detailed list of error codes is available here.

On this page

HTTP request Parameters Response