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..."
}

Run

A 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 the AI assistant during pattern-detection runs and surfaced as references inside an buzzabout__ask response. They aren't a directly-create-able public API surface in v1; you discover them through the assistant.

Where this maps in the product

• The web app's dataset is a dataset.
• The REST API lets you do everything the web app can, scoped to one account by API key.
• The MCP server exposes a thin set of tools so an LLM client like Claude can drive the same workflow.
• The AI assistant sits behind buzzabout__ask (MCP) — it can create datasets, kick off runs, and analyse the results conversationally.

Next up: quickstart — five minutes from zero to a finished dataset.