Quickstart

Five minutes from a fresh API key to your first dataset and mentions list — in Python.

Spin up your first dataset in five minutes. By the end you'll have an API key, a dataset populated with real social-media posts, and a list of mentions you can work with.

This guide uses Python with httpx. The same calls work from any language — pick the request library you prefer. Every example URL, header, and body shape is identical.

Prerequisites

A buzzabout account (sign up — the free tier is enough for this walkthrough).
Python 3.10+ and httpx (pip install httpx).

Want your coding agent to do this for you?

Paste this whole page (or https://docs.buzzabout.ai/llms-full.txt) into Claude Code, Cursor, or any coding assistant and ask it to wire buzzabout into your project. The docs are written to be agent-readable.

Walkthrough

Get an API key

Open Settings → API keys in the web app and click New key. Copy the value (it starts with bz_live_) somewhere safe — you'll see it once.

export BUZZABOUT_KEY="bz_live_abcdef1234567890abcdef1234567890"

The raw key is never stored

buzzabout only stores the SHA-256 digest of your key, not the key itself. Once you close the "New key" dialog the raw value is gone — if you lose it, mint a new one. See authentication for the full lifecycle.

Using an LLM client?

If you're integrating buzzabout with Claude, Cursor, ChatGPT, or another assistant instead of calling the API yourself, skip ahead to Use in your agent. You'll wire the buzzabout MCP server into your assistant and let it drive the same workflow.

Set up the client

A tiny helper to keep the rest of the code clean:

quickstart.py

import os
import time
import httpx

BUZZABOUT_KEY = os.environ["BUZZABOUT_KEY"]
BASE_URL = "https://api.buzzabout.ai"

client = httpx.Client(
    base_url=BASE_URL,
    headers={"x-api-key": BUZZABOUT_KEY},
    timeout=30.0,
)

Create a dataset

A dataset is a named container for the mentions you'll collect.

quickstart.py (continued)

response = client.post("/v1/datasets", json={"name": "cold brew"})
response.raise_for_status()
dataset = response.json()["data"]
dataset_id = dataset["id"]
print(f"Created dataset {dataset_id}: {dataset['name']}")

201 Created

{
  "status": "success",
  "data": {
    "id": "ds_2NK4Y3JxhJ8r9c0Y1u5lkjm9Wb1",
    "name": "cold brew",
    "created_at": "2026-05-01T12:00:00Z"
  }
}

Trigger a dataset run

A run is what actually collects posts from social platforms. The call is asynchronous — it returns 202 Accepted immediately with a run in pending state.

quickstart.py (continued)

response = client.post(
    f"/v1/datasets/{dataset_id}/runs",
    json={
        "search_query": {
            "type": "prompt",
            "sources": ["reddit", "tiktok"],
            "search_query": "cold brew coffee",
        },
        "count": 200,
    },
)
response.raise_for_status()
run = response.json()["data"]
run_id = run["id"]
print(f"Queued run {run_id} — status: {run['status']['type']}")

202 Accepted

{
  "status": "success",
  "data": {
    "id": "dr_2NK4ZG2BqkAxK1nT0RZyZbBmZHN",
    "dataset_id": "ds_2NK4Y3JxhJ8r9c0Y1u5lkjm9Wb1",
    "status": { "type": "pending", "steps": [] },
    "created_at": "2026-05-01T12:00:30Z"
  }
}

Poll until completed

quickstart.py (continued)

while True:
    response = client.get(f"/v1/datasets/{dataset_id}/runs/{run_id}")
    response.raise_for_status()
    status = response.json()["data"]["status"]["type"]
    print(f"  status: {status}")
    if status in ("completed", "failed"):
        break
    time.sleep(10)

A 200-post run typically takes 1–3 minutes.

200 OK (completed)

{
  "status": "success",
  "data": {
    "id": "dr_2NK4ZG2BqkAxK1nT0RZyZbBmZHN",
    "dataset_id": "ds_2NK4Y3JxhJ8r9c0Y1u5lkjm9Wb1",
    "status": {
      "type": "completed",
      "steps": [
        { "name": "scraping", "completed_at": 1714564890 },
        { "name": "analysis", "completed_at": 1714565010 }
      ]
    },
    "mentions_count": 200,
    "created_at": "2026-05-01T12:00:30Z",
    "updated_at": "2026-05-01T12:03:30Z"
  }
}

List mentions

Mentions are global — POST /v1/mentions returns all the mentions across every dataset you own. Pass dataset_ids to scope the search.

quickstart.py (continued)

response = client.post(
    "/v1/mentions",
    json={
        "dataset_ids": [dataset_id],
        "limit": 5,
        "sort": "engagement_rate",
        "order": "desc",
    },
)
response.raise_for_status()
mentions = response.json()["data"]
for m in mentions:
    print(f"  {m['source']:9}  {m['num_likes']:6,} likes  {m['url']}")

200 OK

{
  "status": "success",
  "data": [
    {
      "source": "reddit",
      "id": "t3_1oqliu8",
      "author": {
        "title": "u/sipdaily",
        "url": "https://www.reddit.com/user/sipdaily/",
        "follower_count": 1240
      },
      "text": "Nobody tells you that nitro cold brew tastes...",
      "url": "https://www.reddit.com/r/coffee/comments/1oqliu8/",
      "num_views": 12400,
      "num_likes": 248,
      "engagement_rate": "0.020",
      "datasets": [
        { "id": "ds_2NK4Y3JxhJ8r9c0Y1u5lkjm9Wb1", "name": "cold brew" }
      ]
    }
  ],
  "has_next": true,
  "cursor": "eyJzb3J0X3ZhbHVlIjogIjAuMDIwIiwgImlkIjogInQzXzFvcWxpdTgifQ=="
}

Next steps

Run your first analysis — end-to-end walkthrough including audience scraping and the AI assistant.
MCP overview — drive the same workflow from an MCP-capable assistant (Claude, Cursor, ChatGPT, your own SDK).
API / Datasets — the full reference for the calls we just made.

On this page