Skip to main content

​
Overview

The List Reports endpoint retrieves all reports generated by the authenticated user, with optional filtering by client. Reports are returned in reverse chronological order (newest first) and include associated client information.

​
Endpoint

GET /api/reports

​
Authentication

Requires authentication via NextAuth.js session cookie.

​
Query Parameters

​
clientId
string
Filter reports by a specific client ID. Only returns reports for the specified client if the client belongs to the authenticated user.

​
Response

​
Success Response (200 OK)

Returns an array of report objects with nested client data:
​
reports
array
Array of report objects

​
Error Responses

{
  "error": "Unauthorized"
}

​
Example Requests

​
Get All Reports

curl -X GET https://your-domain.com/api/reports \
  -H "Cookie: next-auth.session-token=..."

​
Get Reports for Specific Client

curl -X GET "https://your-domain.com/api/reports?clientId=clx1234567890" \
  -H "Cookie: next-auth.session-token=..."

​
Example Response

[
  {
    "id": "clxreport123",
    "title": "Standard Report - Acme Corp (2024-01-01 to 2024-01-31)",
    "status": "COMPLETED",
    "data": {
      "clientName": "Acme Corp",
      "startDate": "2024-01-01",
      "endDate": "2024-01-31",
      "reportType": "standard",
      "gscData": {
        "clicks": 12500,
        "impressions": 450000,
        "ctr": 0.0278,
        "position": 8.5,
        "topQueries": [
          {
            "query": "seo services",
            "clicks": 1250,
            "impressions": 45000,
            "ctr": 0.0278,
            "position": 5.2
          }
        ]
      },
      "ga4Data": {
        "users": 8500,
        "sessions": 12000,
        "bounceRate": 0.42,
        "conversions": 150,
        "newUsers": 5200,
        "engagementRate": 0.68
      },
      "pageSpeedData": {
        "mobile": {
          "score": 78,
          "lcp": 2.4,
          "fid": 85,
          "cls": 0.08
        },
        "desktop": {
          "score": 92,
          "lcp": 1.2,
          "fid": 45,
          "cls": 0.03
        }
      },
      "insights": [
        {
          "id": "insight-1",
          "title": "Strong Search Visibility Growth",
          "description": "Your average search position improved by 15% this month, with particularly strong performance in long-tail keywords.",
          "priority": "high",
          "category": "performance",
          "recommendations": [
            "Continue optimizing for long-tail keywords",
            "Create more content targeting position 6-10 keywords"
          ]
        }
      ],
      "agencyName": "Digital Marketing Pro",
      "dataSourceInfo": {
        "hasGSC": true,
        "hasGA4": true,
        "hasPageSpeed": true,
        "pageSpeedFromRequest": true,
        "metricsCount": 12,
        "aiInsightsAvailable": true
      }
    },
    "pdfUrl": "https://your-blob-storage.com/reports/acme-corp_standard_2024-01-01_2024-01-31_1706789123456.pdf",
    "pdfSize": 524288,
    "processingStartedAt": "2024-02-01T10:25:15.123Z",
    "processingCompletedAt": "2024-02-01T10:25:47.456Z",
    "generationTimeMs": 32333,
    "errorMessage": null,
    "createdAt": "2024-02-01T10:25:15.123Z",
    "updatedAt": "2024-02-01T10:25:47.456Z",
    "clientId": "clx1234567890",
    "userId": "clxuser123",
    "aiInsights": [
      {
        "id": "insight-1",
        "title": "Strong Search Visibility Growth",
        "description": "Your average search position improved by 15% this month.",
        "priority": "high",
        "category": "performance",
        "recommendations": [
          "Continue optimizing for long-tail keywords"
        ]
      }
    ],
    "aiInsightsSource": "ai",
    "aiInsightsGeneratedAt": "2024-02-01T10:25:20.789Z",
    "aiTokensUsed": 2000,
    "aiCostUsd": 0.012,
    "aiError": null,
    "client": {
      "id": "clx1234567890",
      "name": "Acme Corp",
      "domain": "acmecorp.com"
    }
  },
  {
    "id": "clxreport456",
    "title": "Executive Report - Beta Inc (2024-01-01 to 2024-01-31)",
    "status": "COMPLETED",
    "data": {
      "clientName": "Beta Inc",
      "reportType": "executive",
      "gscData": {
        "clicks": 8200,
        "impressions": 320000,
        "ctr": 0.0256,
        "position": 9.2
      },
      "ga4Data": {
        "users": 5600,
        "sessions": 7800,
        "bounceRate": 0.38,
        "conversions": 92
      }
    },
    "pdfUrl": "https://your-blob-storage.com/reports/beta-inc_executive_2024-01-01_2024-01-31_1706789234567.pdf",
    "pdfSize": 256000,
    "processingStartedAt": "2024-02-01T09:15:30.000Z",
    "processingCompletedAt": "2024-02-01T09:15:52.123Z",
    "generationTimeMs": 22123,
    "createdAt": "2024-02-01T09:15:30.000Z",
    "updatedAt": "2024-02-01T09:15:52.123Z",
    "clientId": "clx9876543210",
    "userId": "clxuser123",
    "aiInsightsSource": "ai",
    "client": {
      "id": "clx9876543210",
      "name": "Beta Inc",
      "domain": "betainc.com"
    }
  }
]

​
Filtering Behavior

​
Without clientId Parameter

Returns all reports generated by the authenticated user across all their clients.

​
With clientId Parameter

  1. First verifies that the specified client exists and belongs to the authenticated user
  2. If verification fails, returns 404 error
  3. If verification succeeds, returns only reports for that specific client

​
Sorting

Reports are always returned sorted by createdAt in descending order (newest first). This ensures the most recent reports appear at the top of the list.

​
Data Structure

The data field contains the complete report configuration and analytics data that was used to generate the PDF. This includes:
  • Date Range: Start and end dates for the reporting period
  • Report Type: Executive, standard, or custom
  • Analytics Data: Full GSC, GA4, and PageSpeed metrics
  • Custom Configuration: Selected metrics and custom fields for custom reports
  • Branding: Agency name and logo used in the PDF
  • AI Insights: Complete insights array with recommendations
  • Metadata: Information about data sources and generation parameters
This data structure allows:
  • Re-generating reports with the same configuration
  • Viewing report details without downloading the PDF
  • Analyzing historical metrics and trends
  • Debugging report generation issues

​
Use Cases

​
Dashboard Display

Fetch all reports to display in a reports list or table on the user’s dashboard.

​
Client Portfolio

Filter by clientId to show all reports for a specific client in their detail view.

​
Report History

Track report generation over time for billing, analytics, or compliance purposes.

​
Regeneration

Use the stored data field to regenerate a report with the same configuration.

Build docs developers (and LLMs) love

Get started for freeTalk to us