Concepts

A handful of terms come up everywhere in the product, the API, and the MCP server. Knowing them makes the rest of the docs much shorter to read.

Dataset

A dataset is a named container of mentions. You create one, kick off one or more runs against it, and the runs populate it with posts. The same dataset can hold posts from many runs over time.

{
  "id": "ds_01H...",
  "name": "cold brew",
  "mentions_count": 1247,
  "created_at": "2026-05-01T12:00:00Z",
  "url": "https://app.buzzabout.ai/datasets/ds_01H..."
}

Dataset run

A dataset run is one snapshot of post collection: a search query (or list of URLs), a target post count, optional date range, and the analysis steps to apply. Runs are asynchronous — they return pending and transition through working to completed (or failed).

{
  "id": "dr_01H...",
  "dataset_id": "ds_01H...",
  "status": { "type": "completed", "steps": [...] },
  "params": {
    "search_query": { "type": "prompt", "sources": ["reddit"], "search_query": "..." },
    "count": 200
  },
  "mentions_count": 200
}

Mention

A mention is a single post in a dataset — a Reddit thread, a TikTok video, a YouTube video, an Instagram reel, a LinkedIn post. The same post can appear in multiple datasets (the datasets field on each mention enumerates them).

Each mention carries author metadata, engagement counts (views, likes, comments, shares), the original URL, attached media, and a structured content-analysis layer (sentiment, emotions, hook, CTA, tone of voice, content topics, mentioned brands, entities, and more) when those analyses ran on the parent run.

Audience dataset

An audience dataset is a name-only container for audience runs — runs that collect creator and commenter profiles from the posts in a source dataset. Different audience runs in the same container can target different source datasets over time.

{
  "id": "ad_01H...",
  "name": "cold brew creators",
  "profile_count": 850
}

Audience profile

A profile is one creator or commenter from one audience run. It captures the platform-specific account metadata (username, display name, avatar, verification, follower / following / content counts, bio, external link), an LLM-derived audience layer (creator tier, niche, interest clusters, brand affinities, communication tone, OCEAN personality scores, summary), and a normalised authenticity / engagement profile.

Pattern

A pattern is a recurring shape across mentions — a hook framing, a narrative arc, a visual motif. Patterns are produced by pattern-detection runs and by tracking agents; the resulting pattern_id is retrievable via GET /v1/patterns/{id}.

Next steps

• API / Datasets — the API equivalents of every concept on this page.
• Quickstart — five minutes from zero to a finished dataset.