API AI Visibility Tracking

L'API Tracking est la couche API du module AI Visibility Tracking — elle mesure comment ta marque apparaît dans ChatGPT, Perplexity, Claude, Gemini & Co. Tous les endpoints sont sous /v1/... et team-scoped via auth:sanctum.

Contexte UI : Tracker l'AI Visibility · Doc module : AI Visibility Tracking.

Projets (assistant + runtime)

Les projets de tracking sont créés via un assistant en 5 étapes : dispatcher l'analyse → poller le statut → activer → lancer un run → lire les scores. L'assistant est atomique — l'action activate crée mots-clés, prompts et concurrents ensemble et bascule le projet en mode actif.

Mots-clés + prompts

Un projet de tracking peut faire cohabiter des prompts en plusieurs langues, par exemple en allemand et en polonais pour deux marchés. La langue attribuée à un nouveau prompt se choisit à chaque lancement de génération (champ language), indépendamment de la langue du projet ; le filtre language[] permet d'en lire une seule à la fois.

Sources citées (pipeline outreach)

Insights & scores

Reality Check (AVI)

L'AI Visibility Index agrège 6 dimensions (Awareness, Recommendation, Trust, Coverage, Sentiment, Competitive-Edge) en un score 0–100.

Exemple complet : assistant → run → scores

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

# 1) Démarrer l'analyse
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 jusqu'à completed
while [ "$(curl -s "$BASE/tracking-projects/$PID/analysis-status" \
  -H "Authorization: Bearer $TOKEN" | jq -r .analysis_status)" != "completed" ]; do
  sleep 3
done

# 3) Activation atomique
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) Dispatcher le premier run
curl -X POST "$BASE/tracking-projects/$PID/run" \
  -H "Authorization: Bearer $TOKEN"

# 5) Lire les scores (quand le run est 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 & pièges

• Activate est atomique. Ce n'est qu'après activate que status=active et que les runs peuvent démarrer — avant cela, 409.
• AVI nécessite un run. GET /avi sans run terminé renvoie 404.
• L'analyse de sources citées est par défaut batchée. Sans source_ids, toutes les sources non encore analysées sont traitées.
• Reality-Check-Report est optionnel. Ne le dispatcher que si reality_check_enabled=true dans le projet — sinon erreur de validation.
• language sur analyze est contrôlé. Un code de langue non pris en charge renvoie 422 au lieu de basculer silencieusement vers l'anglais.

Voir aussi : API Projets · Crédits · AI Visibility Tracking · Tracker l'AI Visibility.