API Endpoints

The Vizzybl public API is a JSON REST API for your workspace's GEO data — visibility, monitored prompts, verbatim AI answers, citations — plus metered write actions to run audits and scrape prompts.

• Base URL: https://vizzybl.ai/api/v1
• Auth: Authorization: Bearer vzbl_live_... — see API Authentication

Endpoints

Paths below are relative to the base URL. Standard rate limit = 60 requests/min, 1,000/hr. Heavy = 20 requests/min, 400/hr.

Method	Path	Scope	Rate limit	Description
GET	/brand/me	read:brand	Standard	Brand identity: name, domain, competitors, industries, markets
GET	/engines	read:brand	Standard	AI answer engines supported/tracked
GET	/quota	read:brand	Standard	Credit balance, tier, and per-feature quota usage
GET	/stats	read:visibility	Standard	One-call rollup: brand, latest visibility, top competitors, trend, prompt count
GET	/visibility	read:visibility	Standard	Daily share-of-voice history: mentions, rank, sentiment, competitors
GET	/prompts	read:prompts	Standard	Monitored prompts with aggregated metrics
GET	/prompts/{promptId}	read:prompts	Standard	Single prompt detail
GET	/prompts/{promptId}/metrics-history	read:prompts	Standard	Daily metrics time-series for a prompt
GET	/prompt-responses	read:responses	Heavy	Verbatim AI engine answers with citations, brand mentions, sentiment
GET	/citations	read:citations	Heavy	Cited domains/URLs aggregated across AI answers
GET	/citations/prompts	read:citations	Heavy	Reverse lookup — which prompts cite a given URL or domain
POST	/audits	write:audits	Heavy	Trigger a GEO audit on a URL (async, returns 202 + auditId)
GET	/audits/{auditId}	read:brand	Standard	GEO audit status and scores, for polling
POST	/prompts	write:prompts	Heavy	Create monitored prompts (batch up to 50; optional autoScrape)
POST	/prompts/{promptId}/scrape	write:prompts	Heavy	Trigger a fresh scrape of a prompt across AI engines (async, 202)

Async writes: 202 + poll

Audits and scrapes run in the background. The POST returns 202 Accepted immediately with an ID — poll the matching GET until the work completes:

• POST /audits returns an auditId. Poll GET /audits/{auditId} until the status is complete, then read the scores. Audit credits are held and settled by the audit pipeline, not at request time.
• POST /prompts/{promptId}/scrape returns 202 and charges a prompt_monitor_run credit action. Poll GET /prompts/{promptId} for updated metrics.
• POST /prompts is free — prompts are created immediately at status pending. Scraping them (via autoScrape or the scrape endpoint) is what's metered.

Response envelope

Successful responses share one shape:

{ "data": ..., "pagination": { "nextCursor": "...", "limit": 50 }, "meta": { ... } }

pagination appears only on list endpoints. Errors are { "error": { "code": "...", "message": "..." } }.

Pagination and dates

• limit accepts 1–200 (default 50).
• When pagination.nextCursor is non-null, pass it back verbatim as cursor to fetch the next page. Cursors are opaque — never construct or modify one.
• Dates use YYYY-MM-DD format (for example startDate=2026-04-01&endDate=2026-07-01).
• engines filters accept repeated params: engines=claude&engines=chatgpt.

Error codes

Status	Code	Meaning
400	INVALID_PARAM	A parameter is malformed — the message names which one
401	UNAUTHENTICATED	Key missing, invalid, revoked, or expired
402	INSUFFICIENT_CREDITS	The workspace lacks credits for a metered write
403	INSUFFICIENT_SCOPE	The key lacks the scope this endpoint requires
403	INSUFFICIENT_TIER	The workspace is no longer on an Ultra or Enterprise plan
404	NOT_FOUND	The resource doesn't exist in this workspace
429	RATE_LIMITED	Rate limit exceeded — honor the Retry-After header (seconds) before retrying

Next steps

• API Authentication — create keys and choose scopes
• MCP Server — call these endpoints as tools from Claude, Cursor, or VS Code
• Claude Skill — query the read endpoints from any Claude surface