API de AI Visibility Tracking

La API de Tracking es la capa REST alrededor del módulo AI Visibility Tracking — mide cómo aparece tu marca en ChatGPT, Perplexity, Claude, Gemini y compañía. Todos los endpoints viven bajo /v1/... y están scope al team mediante auth:sanctum.

Contexto UI: Trackear AI Visibility · documentación del módulo: AI Visibility Tracking.

Proyectos (asistente + runtime)

Los Tracking Projects se crean con un asistente de 5 pasos: dispatchar análisis → polling de status → activar → arrancar run → leer scores. La activación es atómica — la acción activate crea keywords, prompts y competitors a la vez y deja el proyecto en producción.

Keywords + Prompts

Cited Sources (pipeline de outreach)

Insights y scores

Reality Check (AVI)

El AI Visibility Index agrega 6 dimensiones (Awareness, Recommendation, Trust, Coverage, Sentiment, Competitive Edge) en un score 0–100.

Ejemplo completo: Asistente → Run → Scores

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

# 1) Iniciar análisis
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 hasta completed
while [ "$(curl -s "$BASE/tracking-projects/$PID/analysis-status" \
  -H "Authorization: Bearer $TOKEN" | jq -r .analysis_status)" != "completed" ]; do
  sleep 3
done

# 3) Activar atómicamente
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) Dispatchar primer run
curl -X POST "$BASE/tracking-projects/$PID/run" \
  -H "Authorization: Bearer $TOKEN"

# 5) Leer scores (cuando el 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"

Notas y pitfalls

• Activate es atómico. Solo después de activate el proyecto está en status=active y los runs se pueden lanzar — antes responde 409.
• AVI necesita un run. GET /avi sin un run finalizado devuelve 404.
• El análisis de cited sources es batched por defecto. Sin source_ids se procesan todas las sources aún sin analizar.
• Reality Check Report es opcional. Solo dispatchar si reality_check_enabled=true en el proyecto — si no, error de validación.

Relacionado: API de Proyectos · Créditos · AI Visibility Tracking · Trackear AI Visibility.