Generating Reports

Overview

Reportr generates professional PDF reports combining:

Google Search Console data - Clicks, impressions, CTR, position, top queries
Google Analytics 4 data - Users, sessions, bounce rate, conversions
PageSpeed Insights - Core Web Vitals and performance scores
AI-generated insights - Claude AI analyzes your data and provides actionable recommendations

Reports are customized with your agency’s branding and can be shared with clients.

Prerequisites

Google APIs configured
Client connected with Google account
Search Console and Analytics properties selected
Active subscription with available report quota

Report Limits by Plan:

Free: 5 reports per month
Starter: 25 reports per month
Professional: 75 reports per month
Agency: 250 reports per month

See /workspace/source/src/lib/plan-limits.ts:15-43 for current limits.

Quick Start

Select a client

Navigate to Dashboard → Clients and choose the client you want to report on.

Click Generate Report

Click the Generate Report button on the client card.

Choose date range

Select the reporting period:

Last 7 days
Last 30 days
Last 90 days
Custom date range

Wait for processing

Report generation takes 1-3 minutes. You’ll see:

Fetching data - Pulling from Google APIs
Generating insights - AI analysis via Claude API
Creating PDF - Building branded report
Completed - Report ready to download

Understanding the Report Generation Process

Behind the Scenes

When you generate a report, Reportr:

Validates quota (see /workspace/source/src/app/api/reports/route.ts:119-139):
- Checks your current billing cycle usage
- Ensures you haven’t exceeded your plan’s monthly limit
- Returns error if quota exceeded
Fetches Google Search Console data:
- API endpoint: /api/clients/[id]/google/search-console
- Retrieves: clicks, impressions, CTR, average position
- Includes top queries with performance metrics
- See implementation in /workspace/source/src/app/api/clients/[id]/google/search-console/route.ts
Fetches Google Analytics 4 data:
- API endpoint: /api/clients/[id]/google/analytics
- Retrieves: users, sessions, bounce rate, conversions
- Supports custom metrics if configured
- See implementation in /workspace/source/src/app/api/clients/[id]/google/analytics/route.ts
Fetches PageSpeed Insights (optional):
- API endpoint: /api/clients/[id]/pagespeed
- Retrieves Core Web Vitals: LCP, FID, CLS
- Performance scores for mobile and desktop
Generates AI insights:
- Sends data to Claude API (Anthropic)
- AI analyzes trends, anomalies, and opportunities
- Returns actionable recommendations
- Tracks token usage and cost (stored in report record)
Creates branded PDF:
- Uses React-PDF for generation
- Applies your agency’s branding (if white-label enabled)
- Includes charts, tables, and AI insights
- Uploads to Vercel Blob storage
Updates database:
- Stores report metadata and PDF URL
- Increments client’s totalReportsGenerated counter
- Updates lastReportGenerated timestamp
- Tracks generation time for performance monitoring

Report Quota Management

Checking Your Usage

View your current usage on the Dashboard:

Reports: 12 / 25 used this cycle
Resets in: 18 days

Reportr uses a 30-day rolling billing cycle starting from when you subscribed, not calendar months. See /workspace/source/src/lib/billing-cycle.ts for cycle management.

What Happens When You Hit the Limit?

If you try to generate a report when at quota:

Error response is returned with:

{
  "error": "You've reached your limit of 25 reports per month on the Starter plan",
  "currentCount": 25,
  "limit": 25,
  "upgradeRequired": true,
  "billingCycle": {
    "start": "2026-02-04",
    "end": "2026-03-06",
    "daysRemaining": 18
  }
}

Upgrade modal appears with options to:
- Upgrade to next plan tier
- Wait until your cycle resets
No report is created - you won’t be charged for failed attempts

See the limit check in /workspace/source/src/app/api/reports/route.ts:119-139

Report Data Structure

Search Console Metrics

From /workspace/source/src/app/api/clients/[id]/google/search-console/route.ts, reports include:

{
  "gscData": {
    "clicks": 1250,
    "impressions": 45000,
    "ctr": 2.78,
    "position": 12.5,
    "topQueries": [
      {
        "query": "seo services",
        "clicks": 340,
        "impressions": 8900,
        "ctr": 3.82,
        "position": 8.2
      }
    ]
  }
}

Analytics 4 Metrics

From /workspace/source/src/app/api/clients/[id]/google/analytics/route.ts, reports include:

{
  "ga4Data": {
    "users": 3450,
    "sessions": 5230,
    "bounceRate": 42.3,
    "conversions": 89
  }
}

You can configure custom metrics for GA4 by editing the client’s settings. Custom metrics are stored in the customMetrics JSON field.

AI Insights Structure

Reports can include AI-generated insights (stored in the aiInsights JSON field):

{
  "aiInsights": [
    {
      "type": "opportunity",
      "title": "High-impression, low-click queries",
      "description": "5 queries have high impressions but CTR below 2%...",
      "priority": "high",
      "actionItems": [
        "Optimize meta descriptions for...",
        "Consider creating dedicated landing pages..."
      ]
    }
  ],
  "aiInsightsSource": "ai",
  "aiTokensUsed": 1250,
  "aiCostUsd": 0.0125
}

Advanced Features

Custom Date Ranges

When using custom date ranges:

Select Custom from the date picker
Choose start and end dates
Restrictions:
- Maximum range: 90 days
- Cannot select future dates
- End date must be after start date

Comparing Reports

To track progress over time:

Generate monthly reports on the same day each month
Use the Reports History page to view past reports
Download multiple reports to compare metrics manually

Future enhancement: Side-by-side report comparison is planned.

Re-generating Reports

If a report fails or you want fresh data:

Failed reports show a Retry button
Retrying counts as a new report against your quota
Successful reports cannot be regenerated (to prevent quota abuse)
Instead, generate a new report with the same date range

Performance and Timeouts

Report generation performance:

Target: < 3 minutes end-to-end
Typical: 1-2 minutes for standard reports
Factors affecting speed:
- Amount of Search Console data (more queries = slower)
- Claude API response time (usually 5-15 seconds)
- PDF complexity (charts, images)

If generation takes longer than 5 minutes:

Check your internet connection
Verify Google API quotas aren’t exceeded
Check Reportr status page for service issues
Contact support if issue persists

Troubleshooting

”Email verification required”

Problem: Cannot generate reports despite having quota Solution:

Free plan users must verify their email address first
Check your inbox for verification email
Paid subscribers bypass this check
See /workspace/source/src/app/api/reports/route.ts:96-106

”Google account not connected”

Problem: Report generation fails immediately Solution:

Go to client settings
Verify Google account shows as connected
If not, click Connect Google Account and re-authorize
Ensure Search Console and Analytics properties are selected
Retry report generation

See the connection check in /workspace/source/src/app/api/clients/[id]/google/search-console/route.ts:58-64

Missing Data in Reports

Problem: Report shows zeros or missing sections Possible causes:

New website: If the site was recently added to Search Console/Analytics:
- Wait 48-72 hours for data to populate
- Try a longer date range
Property mismatch:
- Verify the selected Search Console property matches the domain
- Check Analytics property ID is correct
- Ensure domain property includes all subdomains
No traffic:
- If the site genuinely has no traffic, report will show zeros
- This is expected behavior, not an error
API permissions:
- Reconnect Google account to refresh permissions
- Ensure account has Owner/Full User access to properties

”Failed to fetch data” Errors

Problem: Report status shows “FAILED” with error message Common errors: “Token refresh failed”

Refresh token expired or was revoked
Solution: Disconnect and reconnect Google account

“Rate limit exceeded”

Hit Google API quota limits
Solution: Wait 1 minute and retry, or request quota increase

“Property not found”

Selected property no longer exists or access was removed
Solution: Reconfigure client properties

AI Insights Missing or Fallback Used

Problem: Report uses “rule-based” insights instead of AI Possible causes:

Anthropic API key not configured: Check .env file for ANTHROPIC_API_KEY
API quota exceeded: Check Anthropic dashboard for rate limits
Network timeout: Claude API taking too long to respond
Fallback mode activated: System automatically uses rule-based insights when AI fails

Check the aiInsightsSource field:

"ai" - AI-generated insights (normal)
"rule-based" - Fallback template insights
"fallback" - Error occurred, using generic insights

Report Database Schema

For reference, here’s what’s stored for each report (from /workspace/source/prisma/schema.prisma:110-142):

Field	Type	Description
`id`	String	Unique report identifier
`title`	String	Report title (e.g., “SEO Report - Jan 2026”)
`status`	Enum	PENDING, PROCESSING, COMPLETED, FAILED
`data`	JSON	Full report data (GSC, GA4, PageSpeed)
`pdfUrl`	String?	Vercel Blob URL to PDF file
`pdfSize`	Int?	PDF file size in bytes
`processingStartedAt`	DateTime?	When generation began
`processingCompletedAt`	DateTime?	When generation finished
`errorMessage`	String?	Error details if failed
`generationTimeMs`	Int?	Total generation time
`aiInsights`	JSON?	AI-generated insights array
`aiInsightsSource`	String?	“ai”, “rule-based”, or “fallback”
`aiTokensUsed`	Int?	Claude API tokens consumed
`aiCostUsd`	Float?	Cost in USD for AI generation
`clientId`	String	Associated client
`userId`	String	Report owner

Get Started

Core Features

Guides

Plans & Pricing

Generating Reports

Overview

Prerequisites

Quick Start

Understanding the Report Generation Process

Behind the Scenes

Report Quota Management

Checking Your Usage

What Happens When You Hit the Limit?

Report Data Structure

Search Console Metrics

Analytics 4 Metrics

AI Insights Structure

Advanced Features

Custom Date Ranges

Comparing Reports

Re-generating Reports

Performance and Timeouts

Troubleshooting

”Email verification required”

”Google account not connected”

Missing Data in Reports

”Failed to fetch data” Errors

AI Insights Missing or Fallback Used

Report Database Schema

Next Steps

Customize Branding

Manage Subscription

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Plans & Pricing

​Overview

​Prerequisites

​Quick Start

​Understanding the Report Generation Process

​Behind the Scenes

​Report Quota Management

​Checking Your Usage

​What Happens When You Hit the Limit?

​Report Data Structure

​Search Console Metrics

​Analytics 4 Metrics

​AI Insights Structure

​Advanced Features

​Custom Date Ranges

​Comparing Reports

​Re-generating Reports

​Performance and Timeouts

​Troubleshooting

​”Email verification required”

​”Google account not connected”

​Missing Data in Reports

​”Failed to fetch data” Errors

​AI Insights Missing or Fallback Used

​Report Database Schema

​Next Steps

Customize Branding

Manage Subscription

Build docs developers (and LLMs) love

Overview

Prerequisites

Quick Start

Understanding the Report Generation Process

Behind the Scenes

Report Quota Management

Checking Your Usage

What Happens When You Hit the Limit?

Report Data Structure

Search Console Metrics

Analytics 4 Metrics

AI Insights Structure

Advanced Features

Custom Date Ranges

Comparing Reports

Re-generating Reports

Performance and Timeouts

Troubleshooting

”Email verification required”

”Google account not connected”

Missing Data in Reports

”Failed to fetch data” Errors

AI Insights Missing or Fallback Used

Report Database Schema

Next Steps