AI Visibility Tracking API

The tracking API is the API layer around the AI Visibility Tracking module — it measures how your brand shows up in ChatGPT, Perplexity, Claude, Gemini, and others. All endpoints live under /v1/... and are team-scoped via auth:sanctum.

UI context: Track AI Visibility · module documentation: AI Visibility Tracking.

Projects (wizard + runtime)

Tracking projects are created through a 5-step wizard: dispatch analysis → poll status → activate → start run → read scores. The wizard is atomic — the activate action creates keywords, prompts, and competitors together and switches the project on.

Keywords + prompts

A tracking project can carry prompts in several languages at once, for instance German and Polish for two markets. Which language a new prompt gets is set per generation run (field language), independent of the project's own language; the language[] filter reads out one of them at a time.

Cited sources (outreach pipeline)

Insights & scores

Reality Check (AVI)

The AI Visibility Index aggregates 6 dimensions (Awareness, Recommendation, Trust, Coverage, Sentiment, Competitive Edge) into a score 0–100.

Complete example: wizard → run → scores

TOKEN="$RANKION_API_TOKEN"
BASE="https://rankion.ai/api/v1"

# 1) Start analysis
PID=$(curl -s -X POST "$BASE/tracking-projects/analyze" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"mode":"domain","domain":"example.com","language":"en","country":"US"}' \
  | jq -r .project_id)

# 2) Poll until completed
while [ "$(curl -s "$BASE/tracking-projects/$PID/analysis-status" \
  -H "Authorization: Bearer $TOKEN" | jq -r .analysis_status)" != "completed" ]; do
  sleep 3
done

# 3) Atomic activate
curl -X POST "$BASE/tracking-projects/$PID/activate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "keywords":["best crm","crm software"],
    "competitors":[{"domain":"hubspot.com"}],
    "prompts":[{"prompt":"What is the best CRM?","category":"recommendation"}],
    "platforms":["chatgpt","perplexity"],
    "frequency":"weekly",
    "with_search":true,
    "reality_check_enabled":true
  }'

# 4) Dispatch the first run
curl -X POST "$BASE/tracking-projects/$PID/run" \
  -H "Authorization: Bearer $TOKEN"

# 5) Read scores (once the run is completed)
curl "$BASE/tracking-projects/$PID/scores?from=2026-01-01" \
  -H "Authorization: Bearer $TOKEN"

# 6) AVI + recommendations
curl "$BASE/tracking-projects/$PID/avi" \
  -H "Authorization: Bearer $TOKEN"

Notes & pitfalls

• Activate is atomic. Only after activate is status=active and runs can start — before that, 409.
• AVI needs a run. GET /avi without a completed run returns 404.
• Cited-source analysis is batched by default. Without source_ids, all previously unanalyzed sources are processed.
• Reality Check report is optional. Only dispatch if reality_check_enabled=true on the project — otherwise validation error.
• language on analyze is validated. An unsupported language code returns 422 instead of silently falling back to English.

Related: Projects API · Credits · AI Visibility Tracking · Track AI Visibility.