API de Reports

La API de Reports genera reportes completos de Tracking Project en Markdown — incluido executive summary, bloque de KPIs, wins/risks y agregaciones JSON. El generador es async (job: GenerateTrackingProjectReportJob) y combina datos de Site Audit, Rank Tracker, Backlinks y AVI. Documentación completa del módulo: Reports.

Autenticación: Authorization: Bearer <token>, todos los endpoints scope al team.

Endpoints

Rate limit: POST /generate-report está limitado a 1 request / 30 min / proyecto. Llamadas siguientes demasiado tempranas devuelven 429 {error:"rate_limited"}.

Valores de status: pending → generating → completed (o failed).

Workflow de 3 pasos: dispatch → poll → extract

Patrón estándar para consumir la Reports API.

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

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

# 2) Polling hasta 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) Extraer Markdown
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/reports/$RID" \
  | jq -r '.markdown_content' > tracking-output.md

Forma de la response

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"
}

Cross-module correlation

GET /v1/tracking-projects/{id}/correlation agrega tres puntos de datos en un único roundtrip:

• site_audit_ranking_risks — keywords con top ranking cuya landing page tiene issues de Site Audit (risk score 0–10)
• backlinks_av_correlation — correlación de Pearson velocidad de backlinks vs. tendencia AVI sobre 30 días
• smart_todos — recomendaciones de acción priorizadas derivadas de las correlaciones

{
  "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
      }
    ]
  }
}

Códigos de status

Pitfalls

• No streamees el Markdown. markdown_content puede llegar a varios cientos de kB — recíbelo como JSON, no por SSE.
• El export PDF es frontend-side. La API solo entrega Markdown; el PDF se genera en la UI vía Browser Print.
• Comprueba el status failed. Sin la rama de failure, el polling se topa contra el rate limit de 30 min.
• No cachees correlation. El endpoint calcula on-demand — si lo llamas con frecuencia, mete una capa de caché propia en el cliente.

Relacionado: Módulo Reports · API de Tracking · API de Créditos.