Mentions

Search

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

Searches for mentions in the project.

Path parameters#

project_id string required

ID of the project

Request body required application/json #

size integer

Count of results to return

Range0 ≤ size ≤ 1000
default10
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
sort array of object nullable

List of fields to sort by. In case of a tie on the first field, the second field will be used, and so on. If unspecified, the default is to sort by descending date.

sort[].field string required

Field to sort by

Enum"id""date""infused_at""influence""interactions.total_active""interactions.total_active_owned""interactions.total_interactions""interactions.total_interactions_owned""interactions.total_passive""interactions.total_passive_owned""interactions.earned_media_value""interactions.engagement_rate""interactions.engagement_rate_owned"or any string (open enum)
sort[].order string required

Sort order, ascending or descending

Enum"asc""desc"
next array of (string, number or boolean) nullable

Cursor for fetching the next page of results. See the pagination guide for more details.

examplenull
Request example
{
    "size": 10,
    "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"
        }
    },
    "sort": [
        {
            "field": "id",
            "order": "asc"
        }
    ],
    "next": null
}

Responses#

Successful Response

application/json

Search results

total integer

Total number of mentions matching the search filters

example1234
mentions array of object

List of mentions matching the search filters

mentions[].attachments array of object

List of media associated with the mention

mentions[].attachments[].thumbnail string nullable

URL of the attachment's thumbnail

example"https://example.com/p/123456789012345/attachment_thumbnail.jpg"
mentions[].attachments[].type string

Media type of the attachment

Enum"image""video"or any string (open enum)
mentions[].attachments[].url string
example"https://example.com/p/123456789012345/attachment.jpg"
mentions[].author object nullable
mentions[].author.bio string nullable
example"I like pizza"
mentions[].author.followers integer nullable

Number of followers/subscribers the author has

example1000
mentions[].author.id string

Synthesio ID of the author

example"1234-12345678"
mentions[].author.name string nullable

Full name of the author

example"John Dough"
mentions[].author.native_id string nullable

ID of the author, depending on the site

example"johnny42_1234567"
mentions[].author.profile_picture string nullable

URL of the author's profile picture

example"https://example.com/johnny42/pic.jpg"
mentions[].author.url string nullable

URL of the author's profile

example"https://example.com/johnny42"
mentions[].author.username string nullable
example"johnny42"
mentions[].classifiers array of object
mentions[].classifiers[].id string
example"3jtzum1yqiatavc00llr"
mentions[].classifiers[].name string
example"Pizza toppings"
mentions[].classifier_tags array of object
mentions[].classifier_tags[].id string
example"3jtzum1yqiatavc00llr"
mentions[].classifier_tags[].name string
example"Pizza toppings"
mentions[].content string nullable

Content of the mention; for short mentions this can be empty, the full text being in the title

examplenull
mentions[].copyright string nullable

Copyright information (only present for some licensed mentions)

mentions[].date string

Publication date

Formatdate-time
mentions[].emotion string
Enum"joy""sadness""anger""fear""surprise""disgust""neutral""unassigned"or any string (open enum)
mentions[].hashtags array of string

List of hashtags in the mention's text, without #

example["pizza", "pepperoni"]
mentions[].id string

Synthesio ID of the mention

example"123456789012345"
mentions[].influence number nullable

Influence score of the mention

example123
mentions[].infused_at string

Date when the mention was first added to the project

Formatdate-time
mentions[].interactions object nullable

Interactions counts (likes, views...)

example{"total_active": 42, "total_interactions": 1042, "total_passive": 1000, "updated_at": "2024-01-01T00:00:00Z"}
mentions[].interactions.bluesky object nullable
mentions[].interactions.bluesky.likes integer nullable
mentions[].interactions.bluesky.replies integer nullable
mentions[].interactions.bluesky.reposts integer nullable
mentions[].interactions.bluesky.bookmarks integer nullable
mentions[].interactions.bluesky.quotes integer nullable
mentions[].interactions.douyin object nullable
mentions[].interactions.douyin.favorites integer nullable
mentions[].interactions.douyin.likes integer nullable
mentions[].interactions.douyin.reviews integer nullable
mentions[].interactions.douyin.reposts integer nullable
mentions[].interactions.douyin.views integer nullable
mentions[].interactions.facebook object nullable
mentions[].interactions.facebook.angry_reactions integer nullable
mentions[].interactions.facebook.clicks integer nullable
mentions[].interactions.facebook.comments integer nullable
mentions[].interactions.facebook.haha_reactions integer nullable
mentions[].interactions.facebook.likes integer nullable
mentions[].interactions.facebook.love_reactions integer nullable
mentions[].interactions.facebook.reach integer nullable
mentions[].interactions.facebook.sad_reactions integer nullable
mentions[].interactions.facebook.shares integer nullable
mentions[].interactions.facebook.views integer nullable
mentions[].interactions.facebook.wow_reactions integer nullable
mentions[].interactions.instagram object nullable
mentions[].interactions.instagram.comments integer nullable
mentions[].interactions.instagram.likes integer nullable
mentions[].interactions.instagram.reach integer nullable
mentions[].interactions.instagram.saved integer nullable
mentions[].interactions.instagram.shares integer nullable
mentions[].interactions.instagram.views integer nullable
mentions[].interactions.linkedin object nullable
mentions[].interactions.linkedin.comments integer nullable
mentions[].interactions.linkedin.likes integer nullable
mentions[].interactions.mainstream object nullable
mentions[].interactions.mainstream.facebook_shares integer nullable
mentions[].interactions.mainstream.linked_in_shares integer nullable
mentions[].interactions.mainstream.pinterest_shares integer nullable
mentions[].interactions.pinterest object nullable
mentions[].interactions.pinterest.comments integer nullable
mentions[].interactions.pinterest.likes integer nullable
mentions[].interactions.pinterest.repins integer nullable
mentions[].interactions.reddit object nullable
mentions[].interactions.reddit.score integer nullable
mentions[].interactions.redbook object nullable
mentions[].interactions.redbook.favorites integer nullable
mentions[].interactions.redbook.likes integer nullable
mentions[].interactions.redbook.reposts integer nullable
mentions[].interactions.redbook.reviews integer nullable
mentions[].interactions.threads object nullable
mentions[].interactions.threads.views integer nullable
mentions[].interactions.threads.likes integer nullable
mentions[].interactions.threads.replies integer nullable
mentions[].interactions.threads.reposts integer nullable
mentions[].interactions.threads.quotes integer nullable
mentions[].interactions.threads.shares integer nullable
mentions[].interactions.tiktok object nullable
mentions[].interactions.tiktok.views integer nullable
mentions[].interactions.tiktok.comments integer nullable
mentions[].interactions.tiktok.diggs integer nullable
mentions[].interactions.tiktok.shares integer nullable
mentions[].interactions.tiktok.favorites integer nullable
mentions[].interactions.twitter object nullable
mentions[].interactions.twitter.favorites integer nullable
mentions[].interactions.twitter.replies integer nullable
mentions[].interactions.twitter.retweets integer nullable
mentions[].interactions.twitter.views integer nullable
mentions[].interactions.twitter.bookmarks integer nullable
mentions[].interactions.twitter.quotes integer nullable
mentions[].interactions.wechat object nullable
mentions[].interactions.wechat.likes integer nullable
mentions[].interactions.wechat.like_shares integer nullable
mentions[].interactions.wechat.views integer nullable
mentions[].interactions.weibo object nullable
mentions[].interactions.weibo.favorites integer nullable
mentions[].interactions.weibo.interactions integer nullable
mentions[].interactions.weibo.likes integer nullable
mentions[].interactions.weibo.reposts integer nullable
mentions[].interactions.weibo.reviews integer nullable
mentions[].interactions.weibo.video_views integer nullable
mentions[].interactions.youtube object nullable
mentions[].interactions.youtube.comments integer nullable
mentions[].interactions.youtube.dislikes integer nullable
mentions[].interactions.youtube.favorites integer nullable
mentions[].interactions.youtube.likes integer nullable
mentions[].interactions.youtube.replies integer nullable
mentions[].interactions.youtube.views integer nullable
mentions[].interactions.total_active integer nullable

Total number of active interactions. Active interactions are those where the user actively engages with the content, such as likes, comments, shares, etc.

mentions[].interactions.total_passive integer nullable

Total number of passive interactions. Passive interactions are those where the user passively engages with the content, such as views, impressions, etc.

mentions[].interactions.total_interactions integer nullable

Total number of interactions (active + passive)

mentions[].interactions.total_active_owned integer nullable

Total number of active interactions, including those that are only available on owned posts

mentions[].interactions.total_passive_owned integer nullable

Total number of passive interactions, including those that are only available on owned posts

mentions[].interactions.total_interactions_owned integer nullable

Total number of interactions, including those that are only available on owned posts

mentions[].interactions.earned_media_value number nullable

Earned Media Value, as computed with the dashboard's formula

mentions[].interactions.engagement_rate number nullable

Engagement rate

mentions[].interactions.engagement_rate_owned number nullable

Engagement rate, including interactions that are only available on owned posts

mentions[].interactions.updated_at string nullable

Last update timestamp

Formatdate-time
mentions[].language string nullable

An ISO 639-3 language code, potentially suffixed with an ISO 15924 script for certain languages (currently only Chinese), e.g., zho-Hans and zho-Hant for simplified and traditional characters, respectively. The reserved code qtz is used to indicate an unknown language.

Length3 ≤ length
example"eng"
mentions[].license string nullable

License information (only present for licensed mentions)

mentions[].location object nullable
mentions[].location.country string nullable

An ISO 3166-1 alpha-3 country code. The reserved code ZZZ is used to indicate an unknown country.

Length3 ≤ length ≤ 3
example"USA"
mentions[].native_id string nullable

Unique identifier from the originating platform

example"123456789012345"
mentions[].search_data object nullable

Fields related to Search data, i.e. mentions representing queries made in search engines.

mentions[].search_data.volume integer
example1234
mentions[].search_data.platform string
example"google"
mentions[].search_data.search_term string
example"synthesio"
mentions[].search_data.search_term_english string
example"synthesio"
mentions[].search_data.related_search string
example"synthesio"
mentions[].search_data.related_search_english string
example"synthesio"
mentions[].sentiment string
Enum"positive""negative""neutral""unassigned"
mentions[].site object
mentions[].site.id string

Synthesio ID of the site

example"1650630"
mentions[].site.name string
example"Instagram"
mentions[].site.url string nullable
example"https://www.instagram.com"
mentions[].threading object nullable

Threading information, only set for 'comment' mentions. A 'post' is never the child of another post, so its threading is always None and does not indicate whether other mentions reply to it. A 'comment' with threading set to None means its parent or root post could not be resolved.

mentions[].threading.parent_native_id string nullable

Provider ID of this mention's parent post, if any. None if the mention is the thread's root.

mentions[].threading.root_native_id string nullable

Provider ID of the thread's root post.

mentions[].title string nullable

Title of the mention; for short mentions this can be the integrality of the text

example"Pepperoni pizza is the best!"
mentions[].topics array of object
mentions[].topics[].id string
example"g83vvm8petbjhyfm9eek"
mentions[].topics[].name string
example"Pizza"
mentions[].topics[].parent_id string nullable
example"81xr5i74pn79evgb11pm"
mentions[].topics[].parent_name string nullable
example"Food"
mentions[].type string nullable
Enum"post""comment""repost""quoted_repost"or any string (open enum)
mentions[].url string nullable
example"https://example.com/p/123456789012345"
next array of (string, number or boolean) nullable

Cursor for fetching the next page of results. See the pagination guide for more details.

example[58492848568493, "1828406849305"]
200 example
{
    "total": 1234,
    "mentions": [
        {
            "attachments": [],
            "author": {
                "bio": "I like pizza",
                "followers": 1000,
                "id": "1234-12345678",
                "name": "John Dough",
                "native_id": "johnny42_1234567",
                "profile_picture": "https://example.com/johnny42/pic.jpg",
                "url": "https://example.com/johnny42",
                "username": "johnny42"
            },
            "classifiers": [],
            "classifier_tags": [],
            "content": null,
            "copyright": "string",
            "date": "2024-01-01T00:00:00Z",
            "emotion": "joy",
            "hashtags": [
                "pizza",
                "pepperoni"
            ],
            "id": "123456789012345",
            "influence": 123,
            "infused_at": "2024-01-01T00:00:00Z",
            "interactions": {
                "total_active": 42,
                "total_interactions": 1042,
                "total_passive": 1000,
                "updated_at": "2024-01-01T00:00:00Z"
            },
            "language": "eng",
            "license": "string",
            "location": {
                "country": "USA"
            },
            "native_id": "123456789012345",
            "search_data": {
                "volume": 1234,
                "platform": "google",
                "search_term": "synthesio",
                "search_term_english": "synthesio",
                "related_search": "synthesio",
                "related_search_english": "synthesio"
            },
            "sentiment": "positive",
            "site": {
                "id": "1650630",
                "name": "Instagram",
                "url": "https://www.instagram.com"
            },
            "threading": {
                "parent_native_id": "string",
                "root_native_id": "string"
            },
            "title": "Pepperoni pizza is the best!",
            "topics": [],
            "type": "post",
            "url": "https://example.com/p/123456789012345"
        }
    ],
    "next": [
        58492848568493,
        "1828406849305"
    ]
}