AI Visibility

Check a Brand

curl -X POST https://api.alterlab.io/api/v1/ai-visibility/check \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": ["best web scraping api", "how do I scrape a javascript site"],
    "brand": "AlterLab",
    "competitors": ["Firecrawl", "ScraperAPI"],
    "engines": ["google_ai_overview", "perplexity", "chatgpt"],
    "country": "us",
    "runs_per_prompt": 3,
    "hard_cap_microcents": 500000
  }'

• prompts: 1 to 50 prompts. brand: the name to look for. competitors: up to 20 names to track. brand_domains: up to 20 domains that count as your own citations.
• engines: any of google_ai_overview, google_ai_mode, chatgpt, perplexity, gemini and copilot.
• runs_per_prompt: 1 to 5. Answers vary from run to run, so use more than one when you want a rate.
• country: optional two-letter country code. quote_only: true returns the price without running.

Read the Results

Each answer has the prompt, engine, run index, status, the answer_text, brand_mentioned and brand_position, competitors_mentioned, citations (URL and domain) and a sentiment label. The response adds per-prompt and per-engine aggregates: mention_rate, share_of_voice and citation_share, each with its sample_size. Treat a rate with a sample of one as an observation, not a measurement.

An engine that requires a login returns the status engine_unavailable_logged_out. It is never billed and never worked around.

Price and Hard Cap

Get the worst-case price first with POST /api/v1/ai-visibility/quote (the same body) or quote_only: true. The quote is debited up front and hard_cap_microcents is enforced before any debit: a quote above it returns 422. Only successful answers are billed; failed, blocked and logged-out answers are refunded, so billed equals the sum of successful answer costs.

Runs

GET /api/v1/ai-visibility/runs/{run_id} returns status and billing and GET /api/v1/ai-visibility/runs/{run_id}/results returns the stored answers and aggregates.

Schedules and Trends

Track a brand over time with a recurring check. POST /api/v1/ai-visibility/schedules takes a name, a frequency (default weekly), a config (the same body as a check) and an optional per-run hard_cap_microcents; a run whose quote is over the cap is skipped, not billed. Then:

• GET /api/v1/ai-visibility/schedules lists schedules; GET, PATCH and DELETE on /schedules/{schedule_id} read, change and remove one (history is kept).
• POST /schedules/{schedule_id}/pause and /resume stop and restart it; POST /schedules/{schedule_id}/run runs it now without moving next_run_at.
• GET /schedules/{schedule_id}/runs lists run history and GET /schedules/{schedule_id}/trend returns mention rate and share of voice over time.

The number of active schedules is limited by your balance tier; exceeding it returns 403 schedule_limit_reached.

MCP Tool

alterlab_ai_visibility covers checks and past runs with an action of check (default), quote, status or results. The AI Visibility tool page has a free checker you can try first.