API Reference

Introduction

Every audit, check result, and report is accessible through this API. Same infrastructure as the web application — no separate integration layer.

Authentication

Every request must include an Authorization header with a Bearer token. Two token types are supported:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Authorization: Bearer ga4a_live_abc123def456...

All requests must be made over HTTPS. Unauthenticated requests return 401 Unauthorized.

Base URL

https://ga4-audit-api-1083343464429.europe-west2.run.app

Set Content-Type: application/json on POST/PATCH requests. Binary report downloads (PDF, PPTX, Excel) return a binary stream.

Versioning

Current version: v1. No URL prefix. Breaking changes announced with at least 30 days notice.

Subscribe to the changelog to receive notifications when the API changes.

How audits work

Audits are asynchronous. When you start an audit via POST /audits, the API immediately returns an audit object with status: "queued". The audit is dispatched to a Celery task queue and processed in the background by dedicated workers.

Recommended polling pattern: after starting an audit, poll GET /audits/{id} every 2.5 seconds and check the status field. Stop when status is completed or failed.

// Poll until complete
async function waitForAudit(id: string) {
  while (true) {
    const res = await fetch(`https://ga4-audit-api-1083343464429.europe-west2.run.app/audits/${id}`, {
      headers: { Authorization: "Bearer <token>" },
    });
    const audit = await res.json();
    if (audit.status === "completed" || audit.status === "failed") {
      return audit;
    }
    await new Promise((r) => setTimeout(r, 2500));
  }
}

Webhook delivery (firing on audit.completed and audit.failed) is coming soon and will eliminate the need to poll.

Modules

Each audit runs up to 5 independent modules. You can run all modules (the default) or pass a subset via the modules array when starting an audit. Each module returns its own score, grade, and list of check results.

P0 modules run with every audit and have no external data dependencies. P1/P2 modules require Google Analytics Data API or BigQuery access respectively and are automatically skipped if credentials are unavailable.

Check results

Each module runs a set of checks. Every check returns a CheckResult object with the following structure:

{
  "check_id": "PC-012",
  "check_name": "Data retention window",
  "module_id": "property_config",
  "status": "fail",          // pass | fail | warning | error | skipped
  "severity": "high",        // critical | high | medium | low
  "score_earned": 0,
  "score_possible": 10,
  "message": "Data retention is set to 2 months. Recommended minimum is 14 months.",
  "recommendation": "Navigate to Admin → Data Settings → Data Retention and set to 14 months.",
  "details": { ... }         // check-specific diagnostic data
}

Grades and scores

Overall and per-module scores are expressed as a 0–100 integer. The score is calculated as sum(score_earned) / sum(score_possible) * 100 across all non-skipped checks. Scores map to letter grades as follows:

Properties

A property represents a connected GA4 property. Properties must be connected before audits can be run against them. The user must have analytics.readonly access in Google Analytics for the property to be connectable.

POST /properties/connect — Request body

{
  "property_id": "312155177",       // required — GA4 numeric property ID
  "display_name": "My Website",     // required — human label for this property
  "account_name": "Client Account", // optional — GA4 account name
  "website_url": "https://example.com" // optional — used for crawl-based checks
}

Property object

{
  "id": "1bdf6d89-6e1b-4eb3-b05a-8f4fc86222dc", // internal UUID
  "property_id": "312155177",                    // GA4 numeric ID
  "display_name": "My Website",
  "account_name": "Client Account",
  "measurement_id": "G-ABCDEFG123",              // GA4 measurement ID
  "website_url": "https://example.com",
  "last_audit_score": 82.0,
  "last_audit_at": "2026-04-10T14:00:00Z",
  "is_connected": true,
  "created_at": "2026-01-15T09:00:00Z"
}

Audits

Audits are the core resource. Start an audit against a connected property and optionally restrict which modules run. Poll or receive a webhook when the audit completes, then read the full check results.

POST /audits — Request body

{
  "property_id": "1bdf6d89-6e1b-4eb3-b05a-8f4fc86222dc", // required — internal property UUID
  "modules": [                                            // optional — omit to run all modules
    "property_config",
    "tag_consent",
    "utm_campaign",
    "data_quality",
    "ecommerce"
  ]
}

GET /audits query parameters

AuditDetail object

{
  "id": "e7e79e67-6ab5-497d-b669-cb1a73e9d059",
  "property_uuid": "1bdf6d89-6e1b-4eb3-b05a-8f4fc86222dc",
  "property_id": "312155177",
  "property_name": "My Website",
  "measurement_id": "G-ABCDEFG123",
  "website_url": "https://example.com",
  "status": "completed",       // queued | running | completed | failed | paused
  "overall_score": 82,
  "grade": "B",
  "checks_total": 198,
  "checks_passed": 174,
  "checks_failed": 18,
  "checks_warning": 12,
  "checks_completed": 204,
  "modules": [                  // ModuleResult[]
    {
      "module_id": "property_config",
      "module_name": "Property Configuration",
      "score": 90,
      "grade": "A-",
      "checks_passed": 27,
      "checks_failed": 2,
      "checks_warning": 1,
      "checks_skipped": 0
    }
  ],
  "checks": [                   // CheckResult[] — see Check results section
    {
      "check_id": "PC-001",
      "check_name": "Data retention window",
      "module_id": "property_config",
      "status": "pass",
      "severity": "high",
      "score_earned": 10,
      "score_possible": 10,
      "message": "Data retention is set to 14 months.",
      "recommendation": null,
      "details": {}
    }
  ],
  "created_at": "2026-04-10T14:00:00Z",
  "completed_at": "2026-04-10T14:03:42Z"
}

Reports

Once an audit is completed, download it as a PDF, PPTX, or Excel report. Reports are generated on demand and cached. PPTX and Excel reports require a Pro plan or higher.

Dashboard

Aggregated analytics endpoints for building your own dashboards and trend views.

score-trend query parameters

score-trend response

[
  { "date": "2026-03-01", "score": 78, "grade": "C+", "audit_id": "..." },
  { "date": "2026-03-08", "score": 82, "grade": "B",  "audit_id": "..." },
  { "date": "2026-04-10", "score": 86, "grade": "B+", "audit_id": "..." }
]

top-issues response

[
  {
    "check_id": "PC-012",
    "check_name": "Data retention window",
    "module_id": "property_config",
    "severity": "high",
    "status": "fail",
    "property_name": "My Website",
    "audit_id": "e7e79e67-6ab5-497d-b669-cb1a73e9d059",
    "audit_date": "2026-04-10T14:00:00Z"
  }
]

API Keys

API keys enable service-to-service access without a user session. Keys are scoped to the creating user's account and have the same permissions as a session token for that user. Each key is only shown in full once at creation time — store it securely.

POST /auth/api-keys — Request body

{
  "name": "Production backend" // required — a human label for this key
}

Response (key shown once)

{
  "id": "9f4ab2c1-...",
  "name": "Production backend",
  "api_key": "ga4a_live_abc123def456...", // full key — store this now
  "key_prefix": "ga4a_live_abc1",         // prefix shown in list view
  "created_at": "2026-04-10T14:00:00Z"
}

Manage API keys

Request format

All request bodies must be valid JSON. Set Content-Type: application/json on all POST and PATCH requests. Query parameters are used for filtering and pagination on GET endpoints.

POST /audits HTTP/1.1
Host: api.ga4audits.com
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
  "property_id": "1bdf6d89-6e1b-4eb3-b05a-8f4fc86222dc",
  "modules": ["property_config", "tag_consent"]
}

Response format

All responses are JSON unless you are downloading a binary report. Timestamps are ISO 8601 UTC strings. UUIDs use the standard hyphenated format. Nullable fields are present in the response body with a null value rather than omitted.

Paginated list endpoints return an object with a total count alongside the results array:

{
  "audits": [ ... ],
  "total": 47,
  "limit": 20,
  "offset": 0
}

Error codes

All error responses return a consistent JSON body with a detail field containing a human-readable message:

{ "detail": "Audit not found" }

Rate limits

Rate limits are applied per user (or per API key for Enterprise). Limits reset on a rolling 60-second window.

When you are rate limited, the response will be 429 Too Many Requests. The following headers are returned on every response to help you stay within limits:

Webhooks

Register a URL in account settings. GA4 Audits will POST a signed payload — no polling needed.

Planned payload shape

{
  "event": "audit.completed",
  "created_at": "2026-04-10T14:03:42Z",
  "data": {
    "audit_id": "e7e79e67-6ab5-497d-b669-cb1a73e9d059",
    "property_id": "1bdf6d89-6e1b-4eb3-b05a-8f4fc86222dc",
    "overall_score": 82,
    "grade": "B",
    "status": "completed"
  }
}

All webhook payloads will include an X-GA4Audits-Signature header for request verification.

Changelog