Reports & Cross-Module Correlation

Reports & Cross-Module Correlation is Rankion's consolidation layer. Instead of keeping three tabs open and jumping between AVI Tracking, Site Audit, and backlinks analysis, this module dispatches a job that produces a narrative Markdown report across all relevant modules of a tracking project — executive summary, KPI highlights, wins, risks. Plus: a synchronous correlation endpoint that joins Site Audit × Rank Tracker × Backlinks × AVI in one round-trip into a risk map, backlink-AVI correlation, and smart todos.

What it can do

• Auto-generated reports — GenerateTrackingProjectReportJob bundles all project data into a Markdown document, including a summary_json with headline KPIs, wins, risks.
• Markdown export — the markdown_content is directly usable in Notion, GitHub, email, or as a precursor for PDF.
• Report history — up to 50 recent reports per project, sorted by created_at.
• Cross-module correlation — risk map (which top-10 keywords have critical site-audit issues?), backlink velocity × AVI trend (Pearson correlation, 30-day window), smart todos with priority_score.
• Smart todos — prioritized action items with rationale, reference IDs, and impact estimate — directly actionable.

When to use

• Weekly/monthly stakeholder update — the report reads as a standalone document.
• You want to know which of your ranking URLs have site-audit issues (risk map).
• You want to prove statistically whether your backlink activity actually moves AVI — the Pearson correlation gives you the coefficient plus an observation.
• You need a prioritized todo list argued cross-module instead of skimming 4 module tabs individually.

Workflow

Reports are asynchronous — same pattern as all long-running jobs in Rankion: dispatch, poll, consume.

1. Dispatch report — POST /tracking-projects/{id}/generate-report. Response: 202 with report_id and status: "pending". Rate limit: 1 request / 30 min / project.
2. Poll until completed — GET /reports/{id} every 5 seconds until status goes pending → generating → completed (or failed).
3. Extract Markdown — markdown_content from the detail response. Pasteable directly in Notion or convertible to PDF via pandoc.

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

while true; do
  S=$(curl -s -H "Authorization: Bearer $TOKEN" $BASE/reports/$RID | jq -r '.status')
  [ "$S" = completed ] && break
  [ "$S" = failed ] && exit 1
  sleep 5
done

curl -s -H "Authorization: Bearer $TOKEN" $BASE/reports/$RID \
  | jq -r '.markdown_content' > report.md

Cross-module correlation runs synchronously — no polling.

curl "$BASE/tracking-projects/$PID/correlation" \
  -H "Authorization: Bearer $TOKEN"

API

Response — GET /reports/{id} (truncated).

{
  "id": 42,
  "tracking_project_id": 7,
  "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,
  "generated_at": "2026-04-27T18:14:22+00:00"
}

The correlation response returns three blocks: site_audit_ranking_risks[] (top-ranking URLs with site-audit issues, sorted by risk_score), backlinks_av_correlation (Pearson coefficient with observation text), smart_todos[] (prioritized action items with priority_score, reference IDs).

Credits & Limits

• Report generation: 10 credits per run (POST /tracking-projects/{id}/generate-report).
• Rate limit: 1 report / 30 minutes per project. 429 with {error: "rate_limited"} on violation.
• Correlation: free, synchronous, no limits beyond the standard auth throttle.
• Status codes: 202 (dispatch), 200 (list/detail/correlation), 403 (cross-team / cross-project), 404 (report/project not found), 429 (rate limit).
• Data sources: the report aggregates across all active modules of the project — values are as fresh as the last tracking run / audit / backlink pull.

Related modules

• AI Visibility Tracking — provides AVI score and 30d delta for the headline KPIs.
• Content Audit — provides site-audit issues for the risk map.
• Competitor & Backlinks Analysis — provides backlink velocity for the correlation calculation.
• Agentic Chat — can dispatch reports by question and convert smart todos into action items.