/ Platform API
Platform API
    Chat Platform API v3
    Chat Platform API
    Chat Platform API
    Version 3

    Get advanced analytics metrics

    Copy link

    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

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

    Parameters

    Copy link

    The following table lists the parameters that this action supports.

    Parameters
    RequiredTypeDescription

    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.

    OptionalTypeDescription

    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)

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

    Response

    Copy link

    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.

    {
        "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

    Copy link
    Property nameTypeDescription

    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.