Mentions

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 — nothing is charged. The cost lives on the upstream dataset run that collected the mentions. See Pricing.

Endpoint

List Mentions

Authorization

ApiKeyAuth

x-api-key<token>

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.

dataset_ids?array<string>|

Optional list of dataset ids to scope the search. When omitted, the endpoint returns mentions across every dataset owned by the calling account.

operation?MentionsOperation

Switch on the POST /mentions family. select (the default) returns the existing paginated mentions response; count returns {count: int} skipping pagination/hydration; refs returns only the (source, id) refs for the whole filtered set (capped at MAX_SELECTION_REFS) in a single request. Same body shape, same filter compilation; pagination params (cursor, limit) are ignored when operation is count or refs.

Default"select"

Value in"select" | "count" | "refs"

sources?array<>|null

sort?MentionsSortType

Default"date"

Value in

"date" | "likes" | "engagement_rate" | "views" | "comments" | "shares" | "sentiment_score" | "dataset_run_at" | "ad_flight"

order?Order

Default"desc"

Value in"asc" | "desc"

cursor?string|null

limit?Limit

Default20

Range1 <= value <= 100

filters?array<array<||||||||||||||||||>>|null

collection_uids?array<string>|

Optional list of unified collection ids (see GET /v1/collections) to scope the search — the only way to read the posts inside a curated collection. A query collection's uid is its ds_ id, a curated collection's is its ksuid. Ids the API key may not read are ignored.

parameter_ids?array<string>|

Optional list of custom-parameter ids to fetch alongside each mention. IDs not owned by the calling account are silently dropped (the request as a whole still succeeds). When omitted or empty, the response objects do not carry a parameters field.

pattern_run_ids?array<string>|

Optional list of pattern-detection run ids whose assigned categories to fetch alongside each mention. IDs not owned by the calling account (or runs that never produced a pattern) are silently dropped. When omitted or empty, each mention's pattern_assignments is {}.

pattern_item_ids?array<string>|

Optional list of pattern-item ids to RESTRICT the result to posts assigned to at least one of those items (a row filter, unlike pattern_run_ids which only enriches). Each item belongs to one pattern of one dataset, so the ids are unambiguous; ids with no assigned posts simply match nothing.

q?|null

search_mode?SearchMode

Default"keyword"

Value in"keyword" | "semantic"

Response Body

`application/json`

curl -X POST "https://example.com/v1/mentions" \  -H "Content-Type: application/json" \  -d '{    "dataset_ids": [      "ds_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj"    ],    "filters": [      [        {          "type": "sentiment",          "values": [            "negative"          ]        },        {          "type": "has_media",          "value": true        }      ]    ],    "limit": 20,    "operation": "select",    "order": "desc",    "q": "battery life complaints",    "search_mode": "semantic",    "sort": "date",    "sources": [      "reddit"    ]  }'

{
  "status": "info",
  "data": [
    {
      "source": "reddit",
      "id": "string",
      "content_type": "organic",
      "ad_meta": {
        "advertiser_id": "string",
        "advertiser_name": "string",
        "landing_url": "string",
        "display_format": "string",
        "collation_id": "string",
        "is_active": true,
        "ended_at": 0,
        "publisher_platforms": [
          "string"
        ],
        "cta_text": "string",
        "cta_type": "string",
        "eu_reach": 0,
        "advertiser_avatar_url": "string",
        "duration_sec": 0,
        "creative_group_key": "string",
        "product_category": "string",
        "creative_format": "string",
        "advertiser_page_alias": "string",
        "advertiser_likes": 0,
        "advertiser_category": "string",
        "advertiser_verified": true,
        "advertiser_ig_username": "string",
        "advertiser_ig_followers": 0,
        "advertiser_ig_verified": true
      },
      "ad_flight_days": 0,
      "ad_flight_seconds": 0,
      "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": ""
        }
      ],
      "sound": {
        "name": "string",
        "author": "string",
        "cover_image_url": "string",
        "url": "string"
      },
      "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",
        "evidence": "string"
      },
      "narrative_structure": {
        "text": "string",
        "evidence": "string"
      },
      "speech_tempo": "string",
      "music_genre": "string",
      "vibe": {
        "property1": 0,
        "property2": 0
      },
      "hooks": [
        {
          "type": "string",
          "text": ""
        }
      ],
      "cta": {
        "text": "string",
        "evidence": "string"
      },
      "content_topics": [
        {
          "text": "string",
          "evidence": "string"
        }
      ],
      "questions": [
        {
          "text": "string",
          "evidence": "string"
        }
      ],
      "mentioned_brands": [
        "string"
      ],
      "entities": [
        "string"
      ],
      "language": "string",
      "summary": "string",
      "created_at": 0,
      "dataset_run_at": 0,
      "datasets": [
        {
          "id": "string",
          "name": "string"
        }
      ],
      "collections": [
        {
          "uid": "string",
          "name": "string"
        }
      ],
      "comments": [
        {
          "id": "string",
          "author_username": "string",
          "author_name": "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
        }
      },
      "pattern_assignments": {
        "property1": [
          {
            "pattern_item_id": "string",
            "name": "string",
            "confidence": "string"
          }
        ],
        "property2": [
          {
            "pattern_item_id": "string",
            "name": "string",
            "confidence": "string"
          }
        ]
      }
    }
  ],
  "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.

Sound metadata

Instagram and TikTok mentions can include provider-supplied sound metadata:

{
  "name": "original sound",
  "author": "Hawaii",
  "cover_image_url": "https://cdn.example.com/sound-cover.jpg",
  "url": "https://www.tiktok.com/music/original-sound-6689804660171082501"
}

name, author, cover_image_url, and url are each nullable. The url is the provider's native sound page when one is available; it is not an audio file URL. The metadata comes from the source platform and may be incomplete. For unsupported sources and other mentions with no collected sound, sound is null. If a later fetch omits sound metadata, the API retains any previously stored sound.

Next steps

Reference types — how references[] and the post:source:id markdown scheme work across the surface.
Mentions in MCP — the equivalent mentions_* tool family for agent integrations.

200application/json

404application/json

422application/json

On this page

`application/json`

`application/json`

`application/json`