Reference for every Vizzybl public API endpoint — scopes, rate limits, async patterns, pagination, and error codes.
Last updated
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.
https://vizzybl.ai/api/v1Authorization: Bearer vzbl_live_... — see API AuthenticationPaths 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 | Tenant 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, SoV/rank trend, monitored-prompt count. |
| GET | /visibility | read:visibility | Standard | Daily share-of-voice / visibility 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, and sentiment. |
| GET | /citations | read:citations | Heavy | Cited domains/URLs aggregated across AI answers. |
| GET | /citations/prompts | read:citations | Heavy | Reverse lookup — which monitored prompts cite a given URL or domain. |
| GET | /citations/stats | read:citations | Heavy | Aggregated citation stats — domain rank, citation share, most-cited URLs, per-competitor breakdown, source-type distribution. |
| GET | /recommendations | read:recommendations | Heavy | Unified recommendation feed merging the Actions Board and nightly Findings/Insights. |
| GET | /bot-traffic | read:traffic | Standard | AI-bot crawler traffic (visits by bot, status, path, day) from server access logs. |
| GET | /tags | read:prompts | Standard | Custom tag dimensions and values used to group monitored prompts. |
| GET | /audits | read:brand | Standard | List GEO audits (history) for the tenant, newest first. |
| GET | /products | read:products | Standard | Product catalog with each product’s latest AI-answer visibility (mention rate, avg rank, sentiment) plus the shopping-journey scores. |
| GET | /products/{productId}/metrics-history | read:products | Standard | Daily AI-answer visibility time-series for one product (mention rate, avg rank, sentiment, co-occurring competitor products). |
| POST | /audits | write:audits | Heavy | Trigger a GEO audit on a URL (async; returns 202 + auditId; credits settled by the audit pipeline). |
| GET | /audits/{auditId} | read:brand | Standard | GEO audit status and scores for polling. |
| POST | /prompts | write:prompts | Heavy | Create monitored prompts (batch ≤50; preview dry-run available). Free to create; scraping is metered. |
| POST | /prompts/{promptId}/scrape | write:prompts | Heavy | Trigger a fresh scrape of a prompt across AI engines (async; 202). Charges prompt_monitor_run. |
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 the scrape endpoint) is what's metered. Send "preview": true for a dry run that reports what would be created without writing.Successful responses share one shape:
{ "data": ..., "pagination": { "nextCursor": "...", "limit": 50 }, "meta": { ... } }
pagination appears only on list endpoints. Errors are { "error": { "code": "...", "message": "..." } }.
limit accepts 1–200 (default 50).pagination.nextCursor is non-null, pass it back verbatim as cursor to fetch the next page. Cursors are opaque — never construct or modify one.YYYY-MM-DD format (for example startDate=2026-04-01&endDate=2026-07-01).engines filters accept repeated params: engines=claude&engines=chatgpt.| 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 |
| 403 | USAGE_PAUSED | The workspace has paused metered usage |
| 404 | NOT_FOUND | The resource doesn't exist in this workspace |
| 400 | BLOCKED | The audit URL is internal or otherwise disallowed — do not retry |
| 422 | PROMPT_LIMIT_REACHED | The monitored-prompt cap is full — pause or archive a prompt first |
| 422 | BRAND_PENDING_DELETION | The brand is scheduled for deletion, so it cannot add or reactivate monitored prompts — cancel the deletion first |
| 429 | RATE_LIMITED | Rate limit exceeded — honor the Retry-After header (seconds) before retrying |
| 429 | MONTHLY_LIMIT | The monthly cap for this action is spent — unlike a rate limit, waiting does not help |
| 500 | CHARGE_FAILED | The credit charge could not be settled; the action did not run |
| 503 | UNAVAILABLE | Temporary upstream failure — retry once after a brief wait |