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.

Analysis report as PDF at the push of a button

On the project page of an AI visibility project you find the card Analysis report as PDF. It brings all measured modules of the project together in one document, with prioritised actions. Modules without a measurement are marked as such in the report, not shown as zeros.

1. Choose the period — Last 30 days, Last 90 days or Last 180 days.
2. Click Create report (10 credits). The report is built in the background; you can leave the page.
3. Download PDF — the card lists the project's last five reports with their period. While one is being built, it shows Being created ….

• Cost: 10 credits per report. Credits are only charged once the report and the PDF are finished. If the run fails, or the balance is not enough at the end, the list says »Nothing was charged.«
• One report per project every 30 minutes. An earlier click is declined with a notice.
• Who can create it: anyone in the team who is allowed to create AI visibility items. Someone who can only view the project sees the list, but no button.
• Language: the report is written in the language of your account.
• Logo and colour: on plans with white label, the PDF carries the logo and colour of the linked content project; otherwise the Rankion design.

What the report contains

The report opens with the Project profile, followed by the Executive Summary, Prioritised actions, AI Visibility and the topic sections, then Rank Tracker, Site Audit, Gap analysis, Backlinks, Content Audit, Citability and the comparison with the previous report. Every figure comes from stored measurements; the topic sections cost nothing extra.

Project profile

The first section says what the project is about: brand, domain, active competitors, assigned topics, the number of active questions and of questions measured in the period, the queried systems with their model, responses and measuring days, and the search mode (with or without web search). It also states which topic assignment the report describes, so you know which version you are reading.

Visibility by topic cluster

Per topic: questions, responses, mentions, visibility and citation rate, followed by the row Total (each response once).

• Topics your project does not have are left out. A topic without any response in the period gets no row, no zero and no »not measured«.
• A topic with responses but 0 mentions stays visible, as 0.0 %. That is exactly where your brand is missing, and where an action starts.
• The row Without topic only appears if there are responses to questions without a topic. If no question has a topic yet, everything sits under Without topic, with a sentence explaining why.
• A question in two topics counts in both. The sum of the topics is then larger than the Total row; the report says so and gives the number of such questions.

Questions in detail

• Questions with the most own mentions — the ten questions whose responses name your brand most often, with hits, responses and the systems that mention you.
• Questions with a gap, by priority — responses that name other brands but not yours. With topics: the three with the highest priority per topic, for at most ten topics. Without topics: the ten most important overall. The column Named instead of you shows who takes your place.

Competitor comparison

Two counting methods sit side by side on purpose, each with its name:

The two rates can differ. Only the brand list allows a comparison with competitors; below it you see your maintained competitors or, if none are maintained, the frequently named brands.

Sources by type

Which sources the AI cites, sorted by Page type (for example Articles, Comparison, FAQ) and by Domain type (for example Blog / magazine, Forum / community, E-commerce / shop, Comparison portal). Anything not classified yet has its own row. Then the Competitors' format profile — which pages are cited when a maintained competitor is named — and Your own cited pages.

Keyword bundles

In the Rank Tracker section the keywords appear as Keywords by group, with up to three examples per group. The Gap analysis is only bundled by group if every keyword opportunity can be assigned to a group; otherwise the plain list stays, so that no opportunity drops out unnoticed.

Every table names its population

Below every table a footnote says what the figures refer to, for example »Population: 412 responses« — plus period, systems and search mode. Sum rows are checked against this population before the report is created. If one does not match, no PDF is produced and nothing is charged.

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).
• Charged only on success: the 10 credits are only booked once the report and the PDF are finished; a failed report costs nothing.
• 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.