Using dimensions

Dimensions split the filtered mentions into buckets. They are used by Mention Analyze only (POST /projects/{project_id}/mentions/_analyze).

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

What a dimension does#

A dimension groups mentions that share a value: one bucket per country, per week, per sentiment, and so on.

dimensions is a list. The first object is the outer split. Each extra dimension subdivides those buckets into sub-buckets.

The following request first splits by month, then splits each month by sentiment, and counts mentions in every bucket:

{
    "filters": {},
    "dimensions": [
        {
            "type": "date",
            "interval": "month"
        },
        {
            "type": "sentiment"
        }
    ],
    "metrics": [
        {
            "type": "volume"
        }
    ]
}

The request gives the following (truncated) response:

{
    "result": {
        "values": {
            "volume": 105323
        },
        "buckets": [
            {
                "id": "2026-01-01T00:00:00Z",
                "type": "date",
                "values": {
                    "volume": 19531
                },
                "buckets": [
                    {
                        "id": "positive",
                        "type": "sentiment",
                        "values": {
                            "volume": 8278
                        }
                    }
                    // other sentiment buckets...
                ]
            },
            {
                "id": "2026-02-01T00:00:00Z",
                "type": "date",
                "values": {
                    "volume": 17955
                },
                "buckets": [
                    {
                        "id": "positive",
                        "type": "sentiment",
                        "values": {
                            "volume": 7772
                        }
                    }
                    // other sentiment buckets...
                ]
            }
            // other month buckets...
        ]
    }
}

The first dimension groups mentions by month, which can be seen by looking at the first level of the response's buckets array. This can be interpreted as a table with one row per month:

The second dimension (second level of buckets) splits each month by sentiment. In the table, this is akin to splitting each month row into sentiment sub-rows:

Order of dimensions#

The order in the list is the nesting order. Swap the two objects and each sentiment is split by month:

{
    "dimensions": [
        {
            "type": "sentiment"
        },
        {
            "type": "date",
            "interval": "month"
        }
    ],
    "metrics": [
        {
            "type": "volume"
        }
    ]
}

{
    "result": {
        "values": {
            "volume": 105323
        },
        "buckets": [
            {
                "id": "positive",
                "type": "sentiment",
                "values": {
                    "volume": 48200
                },
                "buckets": [
                    {
                        "id": "2026-01-01T00:00:00Z",
                        "type": "date",
                        "values": {
                            "volume": 8278
                        }
                    },
                    {
                        "id": "2026-02-01T00:00:00Z",
                        "type": "date",
                        "values": {
                            "volume": 7772
                        }
                    }
                    // other month buckets...
                ]
            }
            // other sentiment buckets...
        ]
    }
}

More dimensions#

Adding an extra dimension is similar to adding another level of buckets, or in our table analogy, adding one more level of sub-rows.

There is no limit to the number of dimensions, however there is a limit to the total number of buckets that can be returned in an analytics request. Since each level multiplies the number of buckets, adding more dimensions can exponentially increase the total number of buckets returned. If you hit an error, try reducing the number of dimensions or the size of each dimension.

Dimensions array format#

dimensions is a JSON array: each item names the dimension in a type field.

These two objects are equivalent. The response bucket type is country in both cases:

{
    "type": "country"
}

{
    "type": "country",
    "name": "country"
}

Set name to relabel the dimension in the response. The request type stays date (monthly buckets). Each response bucket copies that label into its type field:

{
    "type": "date",
    "interval": "month",
    "name": "month"
}

{
    "id": "2026-01-01T00:00:00Z",
    "type": "month",
    "values": {
        "volume": 19531
    }
}

This request groups mentions by country and keeps the 10 most frequent countries:

{
    "type": "country",
    "size": 10
}

Always send type on every dimension object. Filters and dimensions reuse the same identifiers (country, sentiment, …), but the JSON shape differs: a filter puts the identifier in the key, a dimension puts it in type.

country as a filter and as a dimension:

{
    "filters": {
        "country": {"values": ["USA"]}
    }
}

{
    "dimensions": [
        {"type": "country"}
    ]
}

Dimension types#

Date

The date dimension buckets mentions by publication date.

Monthly buckets on the publication date:

{
    "type": "date",
    "interval": "month"
}

If you omit interval, buckets are weeks, not days or months.

Bucket ids are ISO-8601 timestamps at the start of each interval, for example 2026-01-01T00:00:00Z for a month.

Terms

Terms dimensions group mentions by each distinct value of a field and keep those that match the most mentions (the top 10 by default, see size).

These fields apply to every type marked Terms in the Dimensions reference (country, hashtag, sentiment, language, …). They do not apply to date (Date), to named_entity and part_of_speech (Semantics), or to the Filters types below.

Keep only the United States and France, even if other countries would rank higher:

{
    "type": "country",
    "include": ["USA", "FRA"]
}

Semantics

named_entity and part_of_speech behave like Terms, with one extra field.

Projects hide named entities and parts of speech that would clutter a chart: noisy or low-value values, the project's own brand when it dominates the ranking, and similar. That list lives in Synthesio project settings.

By default (ignore_excluded_terms omitted or false), those values do not appear as buckets, so the ranking matches the Synthesio UI. Set it to true when you want the raw top values, including what the project hid (request exclude still applies).

If the project hides Ipsos and that entity matches many mentions:

• false: no Ipsos bucket
• true: an Ipsos bucket can appear

They also accept size, include, exclude, min_doc_count, and missing.

Named entities, including values the project would normally hide:

{
    "type": "named_entity",
    "size": 20,
    "ignore_excluded_terms": true
}

Filters-type dimensions

A few types (age_range, named_entity_category, noise_reducer, part_of_speech_meta_category, publisher_category, publisher_meta_category, social_vs_mainstream) use a fixed set of buckets rather than the most frequent values of a field.

They do not accept name, min_doc_count, or missing.

social_vs_mainstream splits mentions into social platforms (Facebook, X, Instagram, …) versus mainstream media (news, press). Typical bucket ids are social and mainstream.

{
    "type": "social_vs_mainstream"
}

See also#

See Complete example for a full _analyze request with filters and metrics, and the Dimensions reference for every type.