# Buzzview API

> Fetch and manage data via the BuzzView External API (AI visibility monitoring). Use whenever the user wants to pull BuzzView data - projects, AI visibility metrics, share of voice, competitor analysis, brand mentions, citations, or prompt responses. Also use for AI visibility trend analysis across LLMs (ChatGPT, Perplexity, Google AI Overviews, AI Mode), KPI history, creating scheduled projects, or toggling project public-share visibility. Covers all /api/external/v1/ endpoints.

- Skill: `buzzmatic/buzzview-api` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add buzzmatic/buzzview-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/buzzmatic/buzzview-api/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Buzzmatic (https://skillmd.com/u/buzzmatic)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/buzzmatic/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.

```bash
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

| Type | Location | Format |
|------|----------|--------|
| Raw API response | `output/raw/buzzview_{endpoint}_*.json` | JSON |
| Processed flat data | `output/processed/buzzview_{endpoint}_*.csv` | CSV (read endpoints only) |

## Typical Workflows

### Quick project overview
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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:
```bash
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:
```bash
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:
```json
{
  "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
```bash
# 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.