Buzzview API

BuzzView API

Read and write to BuzzView's External API v1. Requires BUZZVIEW_API_KEY env var (starts with bv_).

Read references/api-reference.md for full endpoint details, schemas, and write-payload field reference.

CLI Script

scripts/buzzview_api.py handles all endpoints with automatic pagination, rate-limit retry (honors Retry-After and X-RateLimit-Reset), and file output.

python skills/buzzview-api/scripts/buzzview_api.py \
  --endpoint {endpoint} \
  [--output-dir output] \
  [--project-id N] [--limit N] [--offset N] [--max-results N] \
  [--run-id-bv N] [--search "text"] [--llm chatgpt|perplexity|ai_overview|ai_mode] \
  [--payload-file path.json] [--payload-json '{...}'] [--is-public true|false]

Read endpoints: projects, project, summary, summary-history, visibility, share-of-voice, competitors, citations, prompts, brands

Write endpoints: create-project (POST /projects, admin only), set-visibility (PATCH /projects/{id}/visibility)

All except projects and create-project require --project-id. Returns JSON to stdout with output_files, record_count, and summary. Output files default to ./output/ (override with --output-dir).

Output Files

Typical Workflows

Quick project overview

# List projects
python skills/buzzview-api/scripts/buzzview_api.py --endpoint projects

# Get KPI summary for a project (latest run)
python skills/buzzview-api/scripts/buzzview_api.py --endpoint summary --project-id 42

# KPI history (visibility%, SoV%, sentiment, citation metrics across runs)
python skills/buzzview-api/scripts/buzzview_api.py --endpoint summary-history --project-id 42 --limit 30

AI visibility & SoV trends

# Visibility trend with per-LLM breakdown (last 10 runs)
python skills/buzzview-api/scripts/buzzview_api.py --endpoint visibility --project-id 42

# Share of voice trend with per-LLM breakdown
python skills/buzzview-api/scripts/buzzview_api.py --endpoint share-of-voice --project-id 42 --limit 50

Competitive analysis

# All competitors with metrics
python skills/buzzview-api/scripts/buzzview_api.py --endpoint competitors --project-id 42

# Brand detection across all LLMs
python skills/buzzview-api/scripts/buzzview_api.py --endpoint brands --project-id 42 --max-results 500

Citation and prompt analysis

# Cited URLs
python skills/buzzview-api/scripts/buzzview_api.py --endpoint citations --project-id 42

# Prompts filtered by LLM
python skills/buzzview-api/scripts/buzzview_api.py --endpoint prompts --project-id 42 --llm chatgpt

# Search prompts by keyword
python skills/buzzview-api/scripts/buzzview_api.py --endpoint prompts --project-id 42 --search "perfume"

Specific snapshot comparison

Use --run-id-bv to query a specific BuzzView snapshot instead of the latest:

python skills/buzzview-api/scripts/buzzview_api.py --endpoint summary --project-id 42 --run-id-bv 907

Create scheduled project (admin only)

Write a JSON file with the ExternalProjectCreate schema (see references/api-reference.md), then call:

python skills/buzzview-api/scripts/buzzview_api.py \
  --endpoint create-project --payload-file project.json

Returns 202 Accepted. Non-admin keys get 403 Forbidden. Credits are deducted only at run time, not at creation.

Minimal payload example:

{
  "name": "Acme Q3 monitor",
  "brand_name": "Acme",
  "domain": "acme.com",
  "interval": "Weekly",
  "next_run": "2026-05-05T08:00:00Z",
  "queries": ["best running shoes", "acme review"],
  "competitors": [{"brand_name": "Nike", "domain": "nike.com"}]
}

Toggle public share URL

# Make project public (returns share_url in response)
python skills/buzzview-api/scripts/buzzview_api.py \
  --endpoint set-visibility --project-id 42 --is-public true

# Revoke public access (clears share_url, purges cache)
python skills/buzzview-api/scripts/buzzview_api.py \
  --endpoint set-visibility --project-id 42 --is-public false

Notes

• Rate limits: GET endpoints 100 req/min; POST/PATCH 10 req/min. Script auto-retries on 429.
• Pagination: --max-results controls total records fetched across pages (default 1000). Page size capped at 100.
• Trend / history endpoints (visibility, share-of-voice, summary-history) cap at 50 runs per call.
• Summary fields (single-run /summary): visibility, share_of_voice, sentiment_score (0-100), url_in_sources, url_top3_percentage, avg_position, plus project_id, run_id, run_date, total_queries.
• /summary/history uses _percent suffix variants in runs[]: visibility_percent, share_of_voice_percent, url_in_sources_percent, avg_citation_position, sentiment_score, plus date.
• Visibility / SoV trends include overall_visibility (or share_of_voice) plus per-platform by_llm breakdowns.
• Prompts endpoint returns rich data: full LLM response text/markdown, detected brands with sentiment, entities, and citation positions per platform.
• Counting: all metrics use distinct (query_id, platform) pairs with canonical brand-name grouping to avoid double counting.