API Reports

L'API Reports génère des rapports complets de Tracking-Project en Markdown — incl. executive summary, bloc KPI, wins/risks et agrégations JSON. Le générateur est async (Job : GenerateTrackingProjectReportJob) et combine des données de Site Audit, Rank Tracker, Backlinks et AVI. Doc module complète : Reports.

Authentification : Authorization: Bearer <token>, tous les endpoints team-scoped.

Endpoints

Rate-limit : POST /generate-report est limité à 1 requête / 30 min / projet. Les appels suivants trop précoces renvoient 429 {error:"rate_limited"}.

Valeurs de status : pending → generating → completed (ou failed).

Workflow en 3 étapes : dispatch → poll → extract

Pattern standard pour consommer l'API Reports.

TOKEN="$RANKION_API_TOKEN"
BASE="https://rankion.ai/api/v1"
PID=7   # ID du Tracking-Project

# 1) Dispatch
RID=$(curl -s -X POST "$BASE/tracking-projects/$PID/generate-report" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.report_id')
echo "Report-ID: $RID"

# 2) Poller jusqu'à completed
while true; do
  S=$(curl -s -H "Authorization: Bearer $TOKEN" "$BASE/reports/$RID" | jq -r '.status')
  echo "Status: $S"
  [ "$S" = completed ] && break
  [ "$S" = failed ] && { echo "Failed"; exit 1; }
  sleep 5
done

# 3) Extraire le Markdown
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/reports/$RID" \
  | jq -r '.markdown_content' > tracking-output.md

Formes de réponse

POST /v1/tracking-projects/{id}/generate-report — 202 :

{
  "report_id": 42,
  "tracking_project_id": 7,
  "status": "pending",
  "status_endpoint": "/v1/reports/42",
  "message": "Report dispatched"
}

GET /v1/reports/{id} — 200 (completed) :

{
  "id": 42,
  "tracking_project_id": 7,
  "team_id": 3,
  "user_id": 12,
  "status": "completed",
  "markdown_content": "# Tracking-Report Project XY\n\n## Executive Summary\n...",
  "summary_json": {
    "headline_kpis": { "avi_score": 64, "delta_30d": "+8", "top10_keywords": 14 },
    "wins": ["..."],
    "risks": ["..."]
  },
  "credits_used": 10,
  "error_message": null,
  "generated_at": "2026-04-27T18:14:22+00:00",
  "created_at": "2026-04-27T18:13:40+00:00"
}

Corrélation cross-module

GET /v1/tracking-projects/{id}/correlation agrège trois points de données en un roundtrip :

• site_audit_ranking_risks — mots-clés top-rankés dont la landing page a des issues Site Audit (risk-score 0–10)
• backlinks_av_correlation — corrélation de Pearson entre vélocité backlinks et tendance AVI sur 30 jours
• smart_todos — recommandations d'actions priorisées dérivées des corrélations

{
  "data": {
    "site_audit_ranking_risks": [
      {
        "keyword_id": 91,
        "keyword": "best crm",
        "search_volume": 4400,
        "position": 5,
        "issues_count": 7,
        "critical_count": 2,
        "risk_score": 8.4
      }
    ],
    "backlinks_av_correlation": {
      "correlation_coefficient": 0.612,
      "days_with_data": 14,
      "velocity_total_30d": 23,
      "observation": "Moderat positive Korrelation: Backlink-Velocity beeinflusst AVI."
    },
    "smart_todos": [
      {
        "priority_score": 84,
        "estimated_impact": "medium",
        "title": "Page-Issues fixen die Top-Ranking gefaehrden",
        "reference_type": "tracking_keyword",
        "reference_id": 91
      }
    ]
  }
}

Codes de statut

Pièges

• Ne stream pas le Markdown. markdown_content peut faire plusieurs centaines de kB — récupère-le en JSON, pas via SSE.
• L'export PDF est côté frontend. L'API ne fournit que du Markdown ; le PDF est généré dans l'UI via le print du navigateur.
• Vérifie le statut failed. Sans branche failure, le polling tape sinon contre le rate-limit de 30 min.
• Ne cache pas la corrélation. L'endpoint calcule à la demande — pour des appels fréquents, mets une couche de cache propre côté client.

Voir aussi : Module Reports · API Tracking · Crédits.