buzzabout docsMentions
POST /v1/mentions — global, filterable, paginated mentions across one or more datasets.
The mentions endpoint is global: one call returns mentions from
every dataset owned by the calling account. Pass dataset_ids to scope
the search; omit it to span everything.
The body is POST (not query string) because filters are non-trivially
nested. The full request/response schema, examples, and integrated
playground are below — the prose that follows highlights the parts that
benefit from a longer explanation.
Pricing
Free — no credits charged. The cost lives on the upstream dataset run that collected the mentions. See Pricing.
Endpoint
Authorization
ApiKeyAuth Buzzabout API key, beginning with bz_live_ (or bz_test_ for staging-only keys).
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
curl -X POST "https://example.com/v1/mentions" \ -H "Content-Type: application/json" \ -d '{ "dataset_ids": [ "ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj" ], "filters": { "date_range": { "from": "2026-04-01", "to": "2026-04-30" }, "sentiment": { "in": [ "negative" ] } }, "limit": 20, "operation": "select", "order": "desc", "q": "battery life complaints", "search_mode": "semantic", "sort": "date", "sources": [ "reddit" ] }'{
"status": "info",
"data": [
{
"source": "reddit",
"id": "string",
"author": {
"avatar": {
"type": "image",
"version_list": [
{
"url": "string",
"width": 0,
"height": 0
}
],
"description": ""
},
"title": "string",
"title_url": "string",
"headline": "string",
"headline_url": "string"
},
"title": "string",
"text": "string",
"url": "string",
"media": [
{
"type": "image",
"version_list": [
{
"url": "string",
"width": 0,
"height": 0
}
],
"description": ""
}
],
"num_views": 0,
"are_views_estimated": true,
"num_likes": 0,
"num_comments": 0,
"num_shares": 0,
"engagement_rate": "string",
"sentiment": {
"negative": "string",
"neutral": "string",
"positive": "string"
},
"sentiment_score": "string",
"emotions": {
"neutral": "string",
"joy": "string",
"sadness": "string",
"anger": "string",
"surprise": "string",
"fear": "string",
"disgust": "string"
},
"category": "string",
"content_intention": "string",
"tone_of_voice": {
"text": "string"
},
"narrative_structure": {
"text": "string"
},
"hook": {
"text": "string"
},
"cta": {
"text": "string"
},
"content_topics": [
{
"text": "string"
}
],
"questions": [
{
"text": "string"
}
],
"mentioned_brands": [
"string"
],
"entities": [
"string"
],
"language": "string",
"created_at": 0,
"dataset_run_at": 0,
"datasets": [
{
"id": "string",
"name": "string"
}
],
"collections": [
{
"id": 0,
"name": "string"
}
],
"comments": [
{
"id": "string",
"author_username": "string",
"body": "string",
"num_likes": 0,
"num_replies": 0,
"created_at": "2019-08-24T14:15:22Z"
}
],
"parameters": {
"property1": {
"value": null,
"status": "pending",
"computed_at": 0
},
"property2": {
"value": null,
"status": "pending",
"computed_at": 0
}
}
}
],
"has_next": true,
"cursor": "string"
}{
"status": "info",
"error_code": "dataset_not_found",
"detail": "string",
"transient": true
}{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string"
}
]
}Filters
filters is a list of filter groups. Each group is a list of single
filters. Groups are combined with OR, filters within a group with
AND. Maximum 10 filters total across all groups.
The full filter taxonomy:
| Type | Shape |
|---|---|
keyword | { "operator": "is" | "is_not", "value": "..." } — max 2 words. |
sentiment | { "values": ["positive"|"negative"|"neutral"] } |
metric_change | { "metric": "likes"|"views"|"comments"|"engagement_rate", "operator": { ... } } — operator is one of greater_than, less_than, in_range, or changed_by. |
source | { "values": ["reddit", ...] } |
content_topic | { "operator": "any_of", "values": [...] } |
content_intention | { "operator": "any_of", "values": [...] } |
tone_of_voice | { "operator": "any_of", "values": [...] } |
hook | { "operator": "any_of", "values": [...] } |
cta | { "operator": "any_of", "values": [...] } |
mentioned_brands | { "operator": { "type": "any_of"|"equals"|"contains", "values"/"value": ... } } |
country_code | { "values": ["US", "GB"] } — uppercase ISO 3166-1 alpha-2. |
has_media | { "value": true | false } |
dominant_emotion | { "values": ["joy"|"sadness"|"anger"|"fear"|"surprise"|"disgust"|"neutral"] } |
Sort fields
sort accepts: date, likes, engagement_rate, views, comments,
shares, sentiment_score, dataset_run_at.
Cursors are sort-aware. When you change sort between calls, request a
fresh page rather than reusing a cursor from the previous sort — the
validator will reject a mismatched cursor.
Reference types
The datasets and collections arrays on each mention echo a small
subset of references[] types (see Reference types).
Comment bodies, when included, appear inline on the mention via comments;
they are not separate reference entries.
Next steps
- Reference types — how
references[]and thepost:source:idmarkdown scheme work across the surface. - Mentions in MCP — the equivalent
mentions_*tool family for agent integrations.