Run your first analysis

End-to-end — scrape posts, collect audience profiles, then ask the AI assistant to summarise both.

This tutorial assumes you've finished the quickstart and have an API key. We'll chain four endpoints into a single workflow:

Create a dataset and trigger a Reddit run.
Wait for it to complete.
Create an audience dataset, kick off a profile-collection run from the source dataset, and wait for it.
Read the audience profiles.
(Optional) Hand the dataset to the AI assistant via MCP.

The whole flow takes 5–15 minutes depending on platform speed.

Setup

export BUZZABOUT_KEY="bz_live_..."

Walkthrough

Create the source dataset

curl -X POST https://api.buzzabout.ai/v1/datasets \
  -H "x-api-key: $BUZZABOUT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "cold brew" }'

Save the returned data.id as DATASET_ID.

Trigger a run

curl -X POST https://api.buzzabout.ai/v1/datasets/$DATASET_ID/runs \
  -H "x-api-key: $BUZZABOUT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search_query": {
      "type": "prompt",
      "sources": ["reddit"],
      "search_query": "cold brew"
    },
    "count": 200,
    "num_comments_per_post": 5,
    "content_analysis_actions": ["sentiment", "hook", "cta"]
  }'

Save the returned data.id as DATASET_RUN_ID.

Wait for the dataset run to complete

while true; do
  STATUS=$(curl -s https://api.buzzabout.ai/v1/datasets/$DATASET_ID/runs/$DATASET_RUN_ID \
    -H "x-api-key: $BUZZABOUT_KEY" \
    | jq -r '.data.status.type')
  echo "status: $STATUS"
  case "$STATUS" in
    completed|failed) break ;;
  esac
  sleep 10
done

A 200-post Reddit run with sentiment + hook + CTA analysis typically finishes in 1–3 minutes.

List the top mentions

curl -X POST https://api.buzzabout.ai/v1/mentions \
  -H "x-api-key: $BUZZABOUT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_ids": ["'"$DATASET_ID"'"],
    "limit": 5,
    "sort": "engagement_rate",
    "order": "desc",
    "filters": [[{ "type": "sentiment", "values": ["positive"] }]]
  }'

Each row has text, url, the author block, engagement counts, and the analysis fields you opted in to.

Create an audience dataset

curl -X POST https://api.buzzabout.ai/v1/audience_datasets \
  -H "x-api-key: $BUZZABOUT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "cold brew creators" }'

Save the returned data.id as AUDIENCE_DATASET_ID.

Kick off the audience run

curl -X POST https://api.buzzabout.ai/v1/audience_datasets/$AUDIENCE_DATASET_ID/runs \
  -H "x-api-key: $BUZZABOUT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_dataset_id": "'"$DATASET_ID"'",
    "total_profile_count": 200
  }'

The audience pipeline reads the source dataset's posts (across every completed run, deduped, top by created_at DESC), walks authors plus commenters, and stops when 200 profiles are collected. Save the returned data.id as AUDIENCE_RUN_ID.

Wait for the audience run

Same poll loop, different URL:

while true; do
  STATUS=$(curl -s https://api.buzzabout.ai/v1/audience_datasets/$AUDIENCE_DATASET_ID/runs/$AUDIENCE_RUN_ID \
    -H "x-api-key: $BUZZABOUT_KEY" \
    | jq -r '.data.status.type')
  echo "audience status: $STATUS"
  case "$STATUS" in
    completed|failed) break ;;
  esac
  sleep 15
done

Audience runs are slower than dataset runs because each profile is scraped + LLM-enriched. A 200-profile run typically takes 5–10 minutes.

Read the audience profiles

curl -X POST https://api.buzzabout.ai/v1/audience_profiles \
  -H "x-api-key: $BUZZABOUT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audience_dataset_ids": ["'"$AUDIENCE_DATASET_ID"'"],
    "sort": "follower_count",
    "order": "desc",
    "limit": 10
  }'

Each row is a creator/commenter profile with platform metadata, audience metrics, and an LLM-derived layer (creator_tier, content_niche, interest_clusters, summary, etc.).

(Optional) Hand it to the AI assistant via MCP

If you've wired buzzabout into your MCP-capable assistant, ask:

"In dataset ds_01H..., what are the top three hooks pulling on Reddit? Cite specific posts."

Your assistant will call buzzabout__list_mentions (dataset_ids: ["ds_01H..."], sort: engagement_rate), then summarise. Or invoke the chat tool directly:

"Use buzzabout__ask to find recurring narratives across the creators in audience dataset ad_01H...."

buzzabout__ask returns markdown plus structured references — including dataset and audience_dataset ids the assistant pulled in. See Reference types for the resolution endpoints.

Audience datasets persist independently of the source dataset. Once the audience run completes, the profiles stay accessible even if you later soft-delete the source dataset (though new audience runs can no longer target it).

Next steps

API / Datasets — the full parameter reference for the dataset run.
API / Mentions — every filter and sort option for the mentions read.
MCP / Tools reference — every tool the host LLM can call, including buzzabout__ask.

On this page