Reports-API

Die Reports-API generiert vollstaendige Tracking-Project-Reports als Markdown — inkl. Executive Summary, KPI-Block, Wins/Risks und JSON-Aggregationen. Der Generator ist async (Job: GenerateTrackingProjectReportJob) und kombiniert Daten aus Site-Audit, Rank-Tracker, Backlinks und AVI. Volle Modul-Doku: Reports.

Authentifizierung: Authorization: Bearer <token>, alle Endpoints team-scoped.

Endpoints

Rate-Limit: POST /generate-report ist auf 1 Request / 30 Min / Project limitiert. Zu fruehe Folge-Calls liefern 429 {error:"rate_limited"}.

Status-Werte: pending → generating → completed (oder failed).

3-Schritt-Workflow: dispatch → poll → extract

Standard-Pattern fuer den Konsum der Reports-API.

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

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

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

Response-Shapes

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 aggregiert drei Datenpunkte in einem Roundtrip:

• site_audit_ranking_risks — Keywords mit Top-Ranking, deren Landingpage Site-Audit-Issues hat (Risk-Score 0–10)
• backlinks_av_correlation — Pearson-Korrelation Backlink-Velocity vs. AVI-Trend ueber 30 Tage
• smart_todos — Priorisierte Aktions-Empfehlungen abgeleitet aus den Korrelationen

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

Status-Codes

Pitfalls

• Markdown nicht streamen. markdown_content kann mehrere 100 kB gross werden — empfange als JSON, nicht via SSE.
• PDF-Export ist Frontend-seitig. Die API liefert nur Markdown; PDF wird im UI via Browser-Print erzeugt.
• failed-Status pruefen. Ohne Failure-Branch laeuft das Polling sonst gegen den 30-Min-Rate-Limit.
• Correlation nicht cachen. Der Endpoint rechnet on-demand — bei haeufigem Aufruf eigene Cache-Schicht im Client einbauen.

Verwandt: Reports-Modul · Tracking-API · Credits.