Using metrics

Metrics compute a value for each bucket. They are used by Mention Analyze only (POST /projects/{project_id}/mentions/_analyze).

For a visual introduction, see the Analytics introduction. The Metrics reference lists every supported type.

What a metric does#

The following request splits mentions by month and computes three values in every bucket.

volume counts mentions. interactions_total sums the interactions stored on each mention (likes, comments, shares, and the other counters). There is no separate global likes metric. unique_author_count counts distinct authors.

Three metrics
{
    "filters": {},
    "dimensions": [
        {
            "type": "date",
            "interval": "month"
        }
    ],
    "metrics": [
        {
            "type": "volume"
        },
        {
            "type": "interactions_total"
        },
        {
            "type": "unique_author_count"
        }
    ]
}

The corresponding response would look like this:

Response
{
    "result": {
        "values": {
            "volume": 105323,
            "interactions_total": 1237841,
            "unique_author_count": 41847
        },
        "buckets": [
            {
                "id": "2026-01-01T00:00:00Z",
                "type": "date",
                "values": {
                    "volume": 19531,
                    "interactions_total": 214326,
                    "unique_author_count": 9024
                }
            },
            {
                "id": "2026-02-01T00:00:00Z",
                "type": "date",
                "values": {
                    "volume": 17955,
                    "interactions_total": 196841,
                    "unique_author_count": 8284
                }
            }
            // other month buckets...
        ]
    }
}

This can be interpreted as a table where each row corresponds to a bucket and each column corresponds to a metric:

Dimension 1: month	volume	interactions_total	unique_author_count
(all mentions)	105323	1237841	41847
January	19531	214326	9024
February	17955	196841	8284
…	…	…	…

The root values are the totals for every mention that passed the filters. Each month bucket repeats the same three keys.

Renaming metrics#

To change the metric name in the returned values object, set the name field. Keep type as the computation you want to run.

Renamed metric
{
    "filters": {},
    "dimensions": [
        {
            "type": "date",
            "interval": "month"
        }
    ],
    "metrics": [
        {
            "type": "volume"
        },
        {
            "type": "interactions_total",
            "name": "interactions"
        }
    ]
}

Response
{
    "result": {
        "values": {
            "volume": 105323,
            "interactions": 1237841
        },
        "buckets": [
            {
                "id": "2026-01-01T00:00:00Z",
                "type": "date",
                "values": {
                    "volume": 19531,
                    "interactions": 214326
                }
            }
            // other month buckets...
        ]
    }
}