Mentions

Analyze

POST https://api.synthesio.com/v1/projects/{project_id}/mentions/_analyze

Run statistical analysis on mentions in the project.

See the Analytics guide for more details on how to use this endpoint.

Path parameters#

project_id string required

ID of the project

Request body required application/json #

filters object required

Filters allow selecting documents based on various criteria. A document_kind filter is automatically added (unless it is explicitly set) to select "clipping" documents only (i.e. social posts, news, etc.) and exclude other document kinds (search data...)

See the dedicated Filtering guide for more details on how to use filters, and the Filters operator reference for a full list of available filters.

example

{"date": {"values": {"gte": "2025-01-01T00:00:00Z"}}, "language": {"values": ["eng", "fra"]}, "sentiment": {"operator": "must_not", "values": ["negative"]}, "synql": {"values": "\"ice cream\" OR gelato"}}

filters.{key} object

filters.{key}.values any required

The value(s) to match

filters.{key}.operator string

The role of the filter in the filter set

Enum"must""should""must_not"

default"must"

filters.{key}.strict boolean

If strict, the mention must match all the filter's values

defaultfalse

dimensions array of object required

List of dimensions to group mentions by. See the Dimensions operator reference for the full list of available dimensions.

example[{"type": "sentiment"}]

one of

Discriminated by "type"

"type":"date"

dimensions[].type string required

Const"date"

dimensions[].name string nullable

Custom name for this dimension, replacing the value of the buckets' type in the response

dimensions[].interval string

Calendar size of each bucket

Enum"day""week""month""year"

default"week"

"type":"affinities""age""attachment""author""author_bio""brand""channel""city""country""date_list""document_kind""emoji""emotion""family_status""follower_count""gender""hashtag""job""language""license""marital_status""media_type""mention""mention_type""parent_id""private_source""ratings""report_product_review""review_status""root_id""scene""sentiment""site""source""state""token""twitter_type""type""url""weekday"

dimensions[].type string required

Enum"affinities""age""attachment""author""author_bio""brand""channel""city""country""date_list""document_kind""emoji""emotion""family_status""follower_count""gender""hashtag""job""language""license""marital_status""media_type""mention""mention_type""parent_id""private_source""ratings""report_product_review""review_status""root_id""scene""sentiment""site""source""state""token""twitter_type""type""url""weekday"

dimensions[].name string nullable

Custom name for this dimension, replacing the value of the buckets' type in the response

dimensions[].size integer

Maximum number of buckets to return

default10

dimensions[].include array of string nullable

Terms to include in the dimension. No other terms will be considered. Consider setting the size accordingly to keep all the included buckets.

dimensions[].exclude array of string nullable

Terms to exclude from the dimension. All other terms will be considered.

dimensions[].min_doc_count integer

Minimum number of documents required for a bucket to be included

default1

dimensions[].missing string nullable

Value to use for documents missing this dimension

"type":"named_entity""part_of_speech"

dimensions[].type string required

Enum"named_entity""part_of_speech"

dimensions[].name string nullable

Custom name for this dimension, replacing the value of the buckets' type in the response

dimensions[].size integer

Maximum number of buckets to return

default10

dimensions[].include array of string nullable

Terms to include in the dimension. No other terms will be considered. Consider setting the size accordingly to keep all the included buckets.

dimensions[].exclude array of string nullable

Terms to exclude from the dimension. All other terms will be considered.

dimensions[].min_doc_count integer

Minimum number of documents required for a bucket to be included

default1

dimensions[].missing string nullable

Value to use for documents missing this dimension

dimensions[].ignore_excluded_terms boolean

Automatically exclude the project's configured excluded terms

defaultfalse

"type":"age_range""named_entity_category""noise_reducer""part_of_speech_meta_category""publisher_category""publisher_meta_category""social_vs_mainstream"

dimensions[].type string required

Enum"age_range""named_entity_category""noise_reducer""part_of_speech_meta_category""publisher_category""publisher_meta_category""social_vs_mainstream"

dimensions[].size integer

Maximum number of buckets to return

default10

dimensions[].include array of string nullable

Terms to include in the dimension. No other terms will be considered. Consider setting the size accordingly to keep all the included buckets.

dimensions[].exclude array of string nullable

Terms to exclude from the dimension. All other terms will be considered.

metrics array of object required

List of metrics to compute for each bucket of mentions. See the Metrics operator reference for the full list of available metrics.

Items1 ≤ items

example[{"type": "volume"}]

metrics[].type string required

Keyword dictating which metric is computed; see the reference for the full list.

metrics[].name string nullable

Custom name for this metric, replacing the key in the response's values objects.

Request example

{
    "filters": {
        "date": {
            "values": {
                "gte": "2025-01-01T00:00:00Z"
            }
        },
        "language": {
            "values": [
                "eng",
                "fra"
            ]
        },
        "sentiment": {
            "operator": "must_not",
            "values": [
                "negative"
            ]
        },
        "synql": {
            "values": "\"ice cream\" OR gelato"
        }
    },
    "dimensions": [
        {
            "type": "sentiment"
        }
    ],
    "metrics": [
        {
            "type": "volume"
        }
    ]
}

Responses#

Successful Response

application/json

result object

Result of the analytics request

result.values object

Metric values for the whole set of mentions matching the filters

example{"volume": 123}

result.values.{key} number

result.buckets array of object

Buckets for the first dimension

result.buckets[].id string

Key value of the bucket

example"positive"

result.buckets[].type string

Type (or custom name) of the dimension

example"sentiment"

result.buckets[].values object

Metric values for this bucket

example{"volume": 100}

result.buckets[].values.{key} number

result.buckets[].buckets array of object

Sub-buckets for the next dimension level

example[]

result.buckets[].buckets[].id string

Key value of the bucket

example"positive"

result.buckets[].buckets[].type string

Type (or custom name) of the dimension

example"sentiment"

result.buckets[].buckets[].values object

Metric values for this bucket

example{"volume": 100}

result.buckets[].buckets[].values.{key} number

result.buckets[].buckets[].buckets array of object

Sub-buckets for the next dimension level

example[]

result.buckets[].buckets[].buckets[].id string

Key value of the bucket

example"positive"

result.buckets[].buckets[].buckets[].type string

Type (or custom name) of the dimension

example"sentiment"

result.buckets[].buckets[].buckets[].values object

Metric values for this bucket

example{"volume": 100}

result.buckets[].buckets[].buckets[].values.{key} number

result.buckets[].buckets[].buckets[].buckets array of object

Sub-buckets for the next dimension level

example[]

result.buckets[].buckets[].buckets[].buckets[].id string

Key value of the bucket

example"positive"

result.buckets[].buckets[].buckets[].buckets[].type string

Type (or custom name) of the dimension

example"sentiment"

result.buckets[].buckets[].buckets[].buckets[].values object

Metric values for this bucket

example{"volume": 100}

result.buckets[].buckets[].buckets[].buckets[].values.{key} number

result.buckets[].buckets[].buckets[].buckets[].buckets array of object recursive

Sub-buckets for the next dimension level

example[]

200 example

{
    "result": {
        "values": {
            "volume": 123
        },
        "buckets": [
            {
                "id": "positive",
                "type": "sentiment",
                "values": {
                    "volume": 100
                },
                "buckets": []
            },
            {
                "id": "neutral",
                "type": "sentiment",
                "values": {
                    "volume": 23
                },
                "buckets": []
            }
        ]
    }
}

Bad request

application/json

errors array of object

Error that caused the request to fail; even though this is a list, it usually contains a single error

errors[].code string

Error code identifying the type of error

errors[].detail string

Message describing the problem

errors[].request_id string

Unique identifier for the request

errors[].meta object nullable

Additional metadata about the error

400 example

{
    "errors": [
        {
            "code": "string",
            "detail": "string",
            "request_id": "string",
            "meta": {}
        }
    ]
}

Unauthorized

application/json

errors array of object

Error that caused the request to fail; even though this is a list, it usually contains a single error

errors[].code string

Error code identifying the type of error

errors[].detail string

Message describing the problem

errors[].request_id string

Unique identifier for the request

errors[].meta object nullable

Additional metadata about the error

401 example

{
    "errors": [
        {
            "code": "string",
            "detail": "string",
            "request_id": "string",
            "meta": {}
        }
    ]
}

Forbidden

application/json

errors array of object

Error that caused the request to fail; even though this is a list, it usually contains a single error

errors[].code string

Error code identifying the type of error

errors[].detail string

Message describing the problem

errors[].request_id string

Unique identifier for the request

errors[].meta object nullable

Additional metadata about the error

403 example

{
    "errors": [
        {
            "code": "string",
            "detail": "string",
            "request_id": "string",
            "meta": {}
        }
    ]
}

Not found

application/json

errors array of object

Error that caused the request to fail; even though this is a list, it usually contains a single error

errors[].code string

Error code identifying the type of error

errors[].detail string

Message describing the problem

errors[].request_id string

Unique identifier for the request

errors[].meta object nullable

Additional metadata about the error

404 example

{
    "errors": [
        {
            "code": "string",
            "detail": "string",
            "request_id": "string",
            "meta": {}
        }
    ]
}

Method not allowed

application/json

errors array of object

Error that caused the request to fail; even though this is a list, it usually contains a single error

errors[].code string

Error code identifying the type of error

errors[].detail string

Message describing the problem

errors[].request_id string

Unique identifier for the request

errors[].meta object nullable

Additional metadata about the error

405 example

{
    "errors": [
        {
            "code": "string",
            "detail": "string",
            "request_id": "string",
            "meta": {}
        }
    ]
}

Internal server error

application/json

errors array of object

Error that caused the request to fail; even though this is a list, it usually contains a single error

errors[].code string

Error code identifying the type of error

errors[].detail string

Message describing the problem

errors[].request_id string

Unique identifier for the request

errors[].meta object nullable

Additional metadata about the error

500 example

{
    "errors": [
        {
            "code": "string",
            "detail": "string",
            "request_id": "string",
            "meta": {}
        }
    ]
}