Reports API

The reports API generates full tracking-project reports as Markdown — including executive summary, KPI block, wins/risks, and JSON aggregations. The generator is async (job: GenerateTrackingProjectReportJob) and combines data from site audit, rank tracker, backlinks, and AVI. Full module documentation: Reports.

Authentication: Authorization: Bearer <token>, all endpoints team-scoped.

Endpoints

Rate limit: POST /generate-report is capped at 1 request / 30 min / project. Earlier follow-up calls return 429 {error:"rate_limited"}.

Status values: pending → generating → completed (or failed).

3-step workflow: dispatch → poll → extract

Standard pattern for consuming the reports API.

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

# 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) Poll until 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) Extract Markdown
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 aggregates three data points in one round-trip:

• site_audit_ranking_risks — keywords with top rankings whose landing page has site-audit issues (risk score 0–10)
• backlinks_av_correlation — Pearson correlation between backlink velocity and AVI trend over 30 days
• smart_todos — prioritized action recommendations derived from the correlations

{
  "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": "Moderately positive correlation: backlink velocity influences AVI."
    },
    "smart_todos": [
      {
        "priority_score": 84,
        "estimated_impact": "medium",
        "title": "Fix page issues that endanger top rankings",
        "reference_type": "tracking_keyword",
        "reference_id": 91
      }
    ]
  }
}

Status codes

Pitfalls

• Do not stream Markdown. markdown_content can grow to several hundred kB — receive as JSON, not via SSE.
• PDF export is frontend-side. The API only returns Markdown; PDF is generated in the UI via browser print.
• Check for failed status. Without a failure branch, polling otherwise runs against the 30-min rate limit.
• Do not cache correlation. The endpoint computes on-demand — for frequent calls add a cache layer in your client.

Related: Reports module · Tracking API · Credits.