AI-Visibility-Tracking-API

Die Tracking-API ist der API-Layer rund um das Modul AI Visibility Tracking — sie misst, wie deine Marke in ChatGPT, Perplexity, Claude, Gemini und Co. erscheint. Alle Endpoints liegen unter /v1/... und sind team-scoped via auth:sanctum.

UI-Kontext: AI-Visibility tracken · Modul-Doku: AI Visibility Tracking.

Projekte (Wizard + Runtime)

Tracking-Projekte werden über einen 5-stufigen Wizard angelegt: Analyse dispatchen → Status pollen → Aktivieren → Run starten → Scores lesen. Der Wizard ist atomic — die activate-Aktion legt Keywords, Prompts, Competitors gemeinsam an und schaltet das Projekt scharf.

Keywords + Prompts

Ein Tracking-Projekt kann Prompts mehrerer Sprachen gleichzeitig führen, zum Beispiel deutsche und polnische für zwei Märkte. Welche Sprache ein neuer Prompt bekommt, legst du je Erzeugungslauf fest (Feld language), unabhängig von der Projektsprache; über den language[]-Filter liest du gezielt eine davon aus.

Cited Sources (Outreach-Pipeline)

Insights & Scores

Reality Check (AVI)

Der AI Visibility Index aggregiert 6 Dimensionen (Awareness, Recommendation, Trust, Coverage, Sentiment, Competitive-Edge) zu einem Score 0–100.

Komplettes Beispiel: Wizard → Run → Scores

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

# 1) Analyse starten
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":"de","country":"DE"}' \
  | jq -r .project_id)

# 2) Polling bis 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) Ersten Run dispatchen
curl -X POST "$BASE/tracking-projects/$PID/run" \
  -H "Authorization: Bearer $TOKEN"

# 5) Scores lesen (wenn Run 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"

Hinweise & Pitfalls

• Activate ist atomic. Erst nach activate ist status=active und Runs lassen sich starten — vorher 409.
• AVI braucht einen Run. GET /avi ohne abgeschlossenen Run liefert 404.
• Cited-Source-Analyse standardmäßig batched. Ohne source_ids werden alle bisher unanalyzed Sources verarbeitet.
• Reality-Check-Report ist optional. Nur dispatchen wenn reality_check_enabled=true im Projekt — sonst Validation-Error.
• language bei analyze wird geprüft. Ein nicht unterstützter Sprachcode liefert 422 statt eines stillen Rückfalls auf Englisch.

Verwandt: Projekte-API · Credits · AI Visibility Tracking · AI-Visibility tracken.