antigravity-seo-kit 2.0.0

package/.agent/skills/seo-google/references/ga4-data-api.md

@@ -0,0 +1,184 @@
+# GA4 Data API v1beta Reference
+
+## Overview
+
+The Google Analytics Data API v1beta provides programmatic access to GA4 report data. For SEO, the primary use case is organic traffic analysis.
+
+**Base URL:** `https://analyticsdata.googleapis.com/v1beta`
+
+## Key Methods
+
+| Method | Description |
+|--------|-------------|
+| `properties.runReport` | Run a standard report |
+| `properties.batchRunReports` | Up to 5 reports in one call |
+| `properties.runRealtimeReport` | Last 30 minutes of data |
+| `properties.getMetadata` | Available dimensions and metrics |
+| `properties.checkCompatibility` | Verify dimension/metric combinations |
+
+## runReport Request
+
+```json
+{
+  "property": "properties/123456789",
+  "dimensions": [
+    { "name": "date" },
+    { "name": "landingPage" }
+  ],
+  "metrics": [
+    { "name": "sessions" },
+    { "name": "totalUsers" }
+  ],
+  "dateRanges": [
+    { "startDate": "28daysAgo", "endDate": "yesterday" }
+  ],
+  "dimensionFilter": {
+    "filter": {
+      "fieldName": "sessionDefaultChannelGroup",
+      "stringFilter": {
+        "matchType": "EXACT",
+        "value": "Organic Search"
+      }
+    }
+  },
+  "orderBys": [
+    { "metric": { "metricName": "sessions" }, "desc": true }
+  ],
+  "limit": 100,
+  "returnPropertyQuota": true
+}
+```
+
+## SEO-Relevant Dimensions
+
+| Dimension | Description |
+|-----------|-------------|
+| `date` | Date in YYYYMMDD format |
+| `pagePath` | Page path (e.g., `/blog/post`) |
+| `landingPage` | Entry page path |
+| `landingPagePlusQueryString` | Entry page with query params |
+| `fullPageUrl` | Full page URL |
+| `pageTitle` | Page title |
+| `sessionSource` | Traffic source (e.g., `google`) |
+| `sessionMedium` | Traffic medium (e.g., `organic`) |
+| `sessionDefaultChannelGroup` | Channel grouping (e.g., `Organic Search`) |
+| `country` | User country |
+| `deviceCategory` | `desktop`, `mobile`, `tablet` |
+| `hostName` | Domain name |
+| `pageReferrer` | Referrer URL |
+
+## SEO-Relevant Metrics
+
+| Metric | Description |
+|--------|-------------|
+| `sessions` | Number of sessions |
+| `totalUsers` | Total unique users |
+| `newUsers` | First-time users |
+| `activeUsers` | Users with engagement |
+| `screenPageViews` | Page views |
+| `bounceRate` | Bounce rate (0-1, multiply by 100 for %) |
+| `averageSessionDuration` | Avg duration in seconds |
+| `engagementRate` | Engaged session rate (0-1) |
+| `keyEvents` | Key events (replaced deprecated `conversions`) |
+| `eventCount` | Total event count |
+
+## Filter Expressions
+
+### String Filter
+
+```json
+{
+  "filter": {
+    "fieldName": "sessionDefaultChannelGroup",
+    "stringFilter": {
+      "matchType": "EXACT",
+      "value": "Organic Search"
+    }
+  }
+}
+```
+
+Match types: `EXACT`, `BEGINS_WITH`, `ENDS_WITH`, `CONTAINS`, `FULL_REGEXP`, `PARTIAL_REGEXP`
+
+### Combining Filters
+
+```json
+{
+  "andGroup": {
+    "expressions": [
+      { "filter": { "fieldName": "country", "stringFilter": { "matchType": "EXACT", "value": "US" }}},
+      { "filter": { "fieldName": "deviceCategory", "stringFilter": { "matchType": "EXACT", "value": "mobile" }}}
+    ]
+  }
+}
+```
+
+Also supports `orGroup` and `notExpression`.
+
+## Date Range Shortcuts
+
+| Value | Meaning |
+|-------|---------|
+| `today` | Current day |
+| `yesterday` | Previous day |
+| `NdaysAgo` | N days ago (e.g., `28daysAgo`) |
+| `YYYY-MM-DD` | Specific date |
+
+Up to 4 date ranges per request (for period-over-period comparison).
+
+## Token-Based Quotas
+
+| Quota | Limit | Scope |
+|-------|-------|-------|
+| Daily tokens | 25,000 | Per property per project |
+| Hourly tokens | 5,000 | Per property per project |
+| Concurrent requests | 10 | Per property per project |
+| Hourly tokens (project-wide) | 1,250 | Per project per property per hour |
+
+Set `returnPropertyQuota: true` to monitor consumption. Simple reports cost ~1-10 tokens; complex ones up to ~100.
+
+## Python Example
+
+```python
+from google.analytics.data_v1beta import BetaAnalyticsDataClient
+from google.analytics.data_v1beta.types import (
+    DateRange, Dimension, Filter, FilterExpression,
+    Metric, OrderBy, RunReportRequest,
+)
+from google.oauth2 import service_account
+
+credentials = service_account.Credentials.from_service_account_file(
+    "service_account.json",
+    scopes=["https://www.googleapis.com/auth/analytics.readonly"],
+)
+
+client = BetaAnalyticsDataClient(credentials=credentials)
+
+request = RunReportRequest(
+    property="properties/123456789",
+    dimensions=[Dimension(name="landingPage")],
+    metrics=[Metric(name="sessions"), Metric(name="totalUsers")],
+    date_ranges=[DateRange(start_date="28daysAgo", end_date="yesterday")],
+    dimension_filter=FilterExpression(
+        filter=Filter(
+            field_name="sessionDefaultChannelGroup",
+            string_filter=Filter.StringFilter(
+                match_type=Filter.StringFilter.MatchType.EXACT,
+                value="Organic Search",
+            ),
+        )
+    ),
+    order_bys=[OrderBy(metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True)],
+    limit=50,
+    return_property_quota=True,
+)
+
+response = client.run_report(request)
+for row in response.rows:
+    print(f"{row.dimension_values[0].value}: {row.metric_values[0].value} sessions")
+```
+
+## Authentication
+- **Scope:** `https://www.googleapis.com/auth/analytics.readonly`
+- Service account must have **Viewer** role in GA4 property
+- Add via GA4 Admin > Property Access Management

package/.agent/skills/seo-google/references/indexing-api.md

@@ -0,0 +1,107 @@
+# Google Indexing API v3 Reference
+
+## Overview
+
+The Indexing API allows you to notify Google when pages are added or removed.
+
+**IMPORTANT:** Officially restricted to pages with **JobPosting** or **BroadcastEvent/VideoObject** structured data. Google may process other page types, but provides no guarantees. Always inform users of this limitation.
+
+## Endpoints
+
+### Publish Notification
+
+**`POST https://indexing.googleapis.com/v3/urlNotifications:publish`**
+
+```json
+{
+  "url": "https://example.com/jobs/software-engineer",
+  "type": "URL_UPDATED"
+}
+```
+
+| Field | Values |
+|-------|--------|
+| `url` | The fully qualified URL |
+| `type` | `URL_UPDATED` (page added/changed), `URL_DELETED` (page removed) |
+
+**Response:**
+```json
+{
+  "urlNotificationMetadata": {
+    "url": "https://example.com/jobs/software-engineer",
+    "latestUpdate": {
+      "url": "https://example.com/jobs/software-engineer",
+      "type": "URL_UPDATED",
+      "notifyTime": "2026-03-27T10:00:00Z"
+    }
+  }
+}
+```
+
+### Get Notification Metadata
+
+**`GET https://indexing.googleapis.com/v3/urlNotifications/metadata?url={ENCODED_URL}`**
+
+Returns `latestUpdate` and `latestRemove` timestamps for the URL.
+
+### Batch Requests
+
+**`POST https://indexing.googleapis.com/batch`**
+
+Up to **100 URLs** per batch request using `multipart/mixed` format:
+
+```
+POST /batch HTTP/1.1
+Content-Type: multipart/mixed; boundary=batch_boundary
+
+--batch_boundary
+Content-Type: application/http
+Content-ID: <item1>
+
+POST /v3/urlNotifications:publish HTTP/1.1
+Content-Type: application/json
+
+{"url": "https://example.com/jobs/1", "type": "URL_UPDATED"}
+--batch_boundary
+Content-Type: application/http
+Content-ID: <item2>
+
+POST /v3/urlNotifications:publish HTTP/1.1
+Content-Type: application/json
+
+{"url": "https://example.com/jobs/2", "type": "URL_UPDATED"}
+--batch_boundary--
+```
+
+## Authentication
+
+- **Scope:** `https://www.googleapis.com/auth/indexing`
+- **Auth type:** Service account (OAuth 2.0)
+- The service account must be **Owner** in Google Search Console for the target domain
+
+## Quotas
+
+| Limit | Value | Scope |
+|-------|-------|-------|
+| Publish requests | **200/day** (default) | Per project |
+| Read-only requests | 180/min | Per project |
+| Total requests | 380/min | Per project |
+
+Request a quota increase: [Indexing API Quota Increase Form](https://developers.google.com/search/apis/indexing-api/v3/quota-increase)
+
+## Error Codes
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 400 | Malformed URL or request body | Check URL format |
+| 403 | Permission denied or quota exceeded | Add service account as Owner in GSC, or check quota |
+| 429 | Rate limit exceeded | Back off and retry with exponential delay |
+| 500/503 | Server error | Retry with exponential backoff |
+
+## Best Practices
+
+1. Submit only URLs with actual content changes (don't spam updates)
+2. Use `URL_DELETED` only when a page is permanently removed (returns 404/410)
+3. Track daily quota usage -- the 200/day limit resets at midnight Pacific Time
+4. For large-scale indexing, use XML sitemaps + Search Console instead
+5. Batch requests count individually against the daily quota (100 batch = 100 quota)

package/.agent/skills/seo-google/references/keyword-planner-api.md

@@ -0,0 +1,66 @@
+# Google Ads API - Keyword Planner Reference
+
+Gold-standard source for keyword search volume. DataForSEO gets its volume data from Google Ads -- this cuts out the middleman.
+
+## Prerequisites (More Complex Than Other Google APIs)
+
+1. **Google Ads Manager Account** -- create at ads.google.com (free to create)
+2. **Developer Token** -- apply at Google Ads API Center (requires Basic access approval)
+3. **OAuth 2.0 credentials** -- reuse existing OAuth client from seo-google config
+4. **For exact volumes**: Run a minimal campaign (~$5-10/day). Without spend, volumes are bucketed ranges ("1K-10K")
+
+## Key Methods
+
+### GenerateKeywordIdeas
+Generate keyword suggestions from seed terms.
+
+**Returns per keyword:**
+- `text`: Keyword string
+- `avg_monthly_searches`: Average monthly volume (exact if spending, bucketed if not)
+- `competition`: LOW / MEDIUM / HIGH (for ads, not organic)
+- `competition_index`: 0-100 competition score
+- `low_top_of_page_bid_micros`: ~20th percentile CPC in micros
+- `high_top_of_page_bid_micros`: ~80th percentile CPC in micros
+- `monthly_search_volumes[]`: Per-month volume for last 12 months
+
+### GenerateKeywordHistoricalMetrics
+Get volume data for specific keywords.
+
+Same return fields as above but for exact keyword list instead of suggestions.
+
+### GenerateKeywordForecastMetrics
+Predict clicks, impressions, and cost for keywords.
+
+## Configuration
+
+Add to `~/.config/claude-seo/google-api.json`:
+
+```json
+{
+  "ads_developer_token": "YOUR_DEV_TOKEN",
+  "ads_customer_id": "123-456-7890",
+  "ads_login_customer_id": "123-456-7890"
+}
+```
+
+## Rate Limits
+
+- Keyword Planning requests are more strictly rate-limited than other Ads API services
+- Exact QPM/QPS not publicly documented
+- Google recommends caching results
+
+## Python Library
+
+```bash
+pip install google-ads
+```
+
+Uses `google-ads` library (separate from `google-api-python-client`).
+
+## Important Notes
+
+- **Volume accuracy**: Without active ad spend, Google returns bucketed ranges ("1K-10K", "10K-100K") instead of exact numbers like "14,800"
+- **Competition score**: Measures advertiser competition for ads, NOT organic ranking difficulty
+- **CPC bids**: Reflect what advertisers pay, useful for estimating keyword commercial value
+- **Location targeting**: Use location IDs (2840 = United States, 2826 = United Kingdom)
+- **Language targeting**: Use language IDs (1000 = English, 1003 = Spanish)

package/.agent/skills/seo-google/references/nlp-api.md

@@ -0,0 +1,55 @@
+# Google Cloud Natural Language API Reference
+
+NLP analysis enhances E-E-A-T scoring by measuring entity coverage, content sentiment, and topic classification using Google's own taxonomy.
+
+## Endpoint
+
+`POST https://language.googleapis.com/v2/documents:annotateText?key={API_KEY}`
+
+## Features
+
+| Feature | What It Does | SEO Use |
+|---------|-------------|---------|
+| `extractEntities` | Extract people, orgs, places, events with salience scores | Topic coverage depth, entity optimization |
+| `extractDocumentSentiment` | Document + sentence-level sentiment score/magnitude | Content tone assessment |
+| `classifyText` | Map content to 700+ Google categories | Topic relevance verification |
+| `moderateText` | Content safety/moderation categories | Content quality flags |
+
+## Entity Types
+
+PERSON, LOCATION, ORGANIZATION, EVENT, WORK_OF_ART, CONSUMER_GOOD, OTHER, PHONE_NUMBER, ADDRESS, DATE, NUMBER, PRICE
+
+Each entity includes:
+- `name`: Entity text
+- `type`: Entity type
+- `salience`: Importance score (0-1, higher = more relevant)
+- `sentiment`: Per-entity sentiment (score + magnitude)
+- `metadata`: Wikipedia URL, MID (Knowledge Graph ID)
+- `mentions`: Occurrences in the text
+
+## Sentiment Scoring
+
+- **Score**: -1.0 (negative) to +1.0 (positive)
+- **Magnitude**: 0 to infinity (emotional intensity, higher = more emotional)
+- Neutral content: score ~0, low magnitude
+- Mixed content: score ~0, HIGH magnitude (both positive and negative)
+
+## Pricing
+
+| Feature | Free/month | Paid (per 1K chars) |
+|---------|-----------|-------------------|
+| Entity Analysis | 5,000 units | $0.001 |
+| Sentiment Analysis | 5,000 units | $0.001 |
+| Content Classification | 30,000 units | $0.002 |
+| Text Moderation | 50,000 units | $0.0005 |
+
+One "unit" = 1,000 characters. Free tier resets monthly.
+
+## Enable the API
+
+1. Go to [console.cloud.google.com/apis/library](https://console.cloud.google.com/apis/library)
+2. Search for "Cloud Natural Language API"
+3. Click Enable
+4. **Billing must be enabled** on the project (free tier still applies)
+
+Uses the same API key as PSI/CrUX.

package/.agent/skills/seo-google/references/pagespeed-crux-api.md

@@ -0,0 +1,204 @@
+# PageSpeed Insights v5 + CrUX API Reference
+
+## Table of Contents
+1. [PageSpeed Insights v5](#pagespeed-insights-v5)
+2. [CrUX API (Daily)](#crux-api-daily)
+3. [CrUX History API (Weekly)](#crux-history-api-weekly)
+4. [Core Web Vitals Thresholds](#core-web-vitals-thresholds)
+
+---
+
+## PageSpeed Insights v5
+
+**Endpoint:** `GET https://www.googleapis.com/pagespeedonline/v5/runPagespeed`
+
+### Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `url` | string | Required. URL to analyze. |
+| `category` | string | `ACCESSIBILITY`, `BEST_PRACTICES`, `PERFORMANCE`, `SEO`. Can specify multiple. |
+| `strategy` | string | `DESKTOP` or `MOBILE` (default). |
+| `locale` | string | Locale for text (e.g., `en`). |
+| `key` | string | API key. Optional but recommended for quota. |
+
+### Response Structure
+
+```
+{
+  "id": "https://example.com/",
+  "loadingExperience": { ... },        // URL-level CrUX data
+  "originLoadingExperience": { ... },  // Origin-level CrUX data
+  "lighthouseResult": {
+    "categories": {
+      "performance": { "score": 0.85 },
+      "accessibility": { "score": 0.92 },
+      "best-practices": { "score": 0.88 },
+      "seo": { "score": 0.95 }
+    },
+    "audits": { ... }                  // Individual audit results
+  },
+  "analysisUTCTimestamp": "2026-03-27T..."
+}
+```
+
+### Field Data Metrics (in loadingExperience)
+
+| PSI Key | CrUX Metric | Unit |
+|---------|-------------|------|
+| `LARGEST_CONTENTFUL_PAINT_MS` | LCP | ms |
+| `INTERACTION_TO_NEXT_PAINT` | INP | ms |
+| `CUMULATIVE_LAYOUT_SHIFT_SCORE` | CLS | unitless |
+| `FIRST_CONTENTFUL_PAINT_MS` | FCP | ms |
+| `EXPERIMENTAL_TIME_TO_FIRST_BYTE` | TTFB | ms |
+
+Each metric contains: `percentile` (p75), `distributions[]` ({min, max, proportion}), `category` (FAST/AVERAGE/SLOW/NONE).
+
+### Key Lighthouse Audit IDs
+
+`first-contentful-paint`, `largest-contentful-paint`, `total-blocking-time`, `cumulative-layout-shift`, `speed-index`, `interactive`
+
+### Rate Limits
+- 25,000 QPD with API key
+- 240 QPM
+- Free, no billing required
+
+### Note on Field Data Migration
+Google is migrating CrUX field data out of PSI. For field data, prefer the CrUX API directly. Use PSI primarily for Lighthouse lab data.
+
+---
+
+## CrUX API (Daily)
+
+**Endpoint:** `POST https://chromeuxreport.googleapis.com/v1/records:queryRecord?key={API_KEY}`
+
+### Request
+
+```json
+{
+  "origin": "https://example.com",
+  "formFactor": "PHONE",
+  "metrics": ["largest_contentful_paint", "interaction_to_next_paint", "cumulative_layout_shift"]
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `origin` | Origin URL (mutually exclusive with `url`) |
+| `url` | Specific page URL (mutually exclusive with `origin`) |
+| `formFactor` | `DESKTOP`, `PHONE`, `TABLET` (optional, omit for all) |
+| `metrics` | Array of metric names (optional, omit for all) |
+
+### Available Metrics
+
+| Metric | Type | Notes |
+|--------|------|-------|
+| `largest_contentful_paint` | int (ms) | Core Web Vital |
+| `interaction_to_next_paint` | int (ms) | Core Web Vital (replaced FID) |
+| `cumulative_layout_shift` | **string** | Core Web Vital. **String-encoded!** Parse carefully. |
+| `first_contentful_paint` | int (ms) | |
+| `experimental_time_to_first_byte` | int (ms) | |
+| `round_trip_time` | int (ms) | Replaced effectiveConnectionType (Feb 2025) |
+| `navigation_types` | fractions | navigate, navigate_cache, reload, etc. |
+| `form_factors` | fractions | desktop/phone/tablet distribution |
+
+### Response
+
+```json
+{
+  "record": {
+    "key": { "origin": "https://example.com" },
+    "metrics": {
+      "largest_contentful_paint": {
+        "histogram": [
+          { "start": 0, "end": 2500, "density": 0.72 },
+          { "start": 2500, "end": 4000, "density": 0.18 },
+          { "start": 4000, "density": 0.10 }
+        ],
+        "percentiles": { "p75": 2100 }
+      },
+      "cumulative_layout_shift": {
+        "percentiles": { "p75": "0.05" }
+      }
+    },
+    "collectionPeriod": {
+      "firstDate": { "year": 2026, "month": 2, "day": 27 },
+      "lastDate": { "year": 2026, "month": 3, "day": 26 }
+    }
+  }
+}
+```
+
+### Important
+- **CLS p75 is a string** (e.g., `"0.05"` not `0.05`). Always parse as float from string.
+- Last histogram bin has **no `end`** (extends to infinity).
+- Densities sum to approximately 1.0.
+- **404** = no data (insufficient Chrome traffic). Not an auth error.
+- Updated daily ~04:00 UTC with ~2 day lag.
+
+### Rate Limits
+- 150 QPM shared between CrUX and CrUX History APIs
+- Free, no paid increase available
+
+---
+
+## CrUX History API (Weekly)
+
+**Endpoint:** `POST https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key={API_KEY}`
+
+Same request format as CrUX API. Returns up to **25 weekly collection periods**.
+
+### Response Differences from CrUX API
+
+Instead of single values, returns timeseries:
+
+```json
+{
+  "record": {
+    "metrics": {
+      "largest_contentful_paint": {
+        "histogramTimeseries": [
+          { "start": 0, "end": 2500, "densities": [0.70, 0.71, 0.72, ...] },
+          { "start": 2500, "end": 4000, "densities": [0.19, 0.18, 0.18, ...] },
+          { "start": 4000, "densities": [0.11, 0.11, 0.10, ...] }
+        ],
+        "percentilesTimeseries": {
+          "p75s": [2200, 2150, 2100, ...]
+        }
+      }
+    },
+    "collectionPeriods": [
+      {
+        "firstDate": { "year": 2025, "month": 9, "day": 29 },
+        "lastDate": { "year": 2025, "month": 10, "day": 26 }
+      },
+      ...
+    ]
+  }
+}
+```
+
+### NaN Handling
+- `"NaN"` string for densities in ineligible periods
+- `null` for percentile values in ineligible periods
+- Always check for these before numeric operations
+
+### Update Schedule
+- Updated **Mondays** ~04:00 UTC
+- Each period = 28-day rolling average ending on a Sunday
+
+---
+
+## Core Web Vitals Thresholds
+
+Current as of March 2026. INP replaced FID on March 12, 2024.
+
+| Metric | Good | Needs Improvement | Poor |
+|--------|------|-------------------|------|
+| **LCP** | ≤ 2,500ms | 2,500–4,000ms | > 4,000ms |
+| **INP** | ≤ 200ms | 200–500ms | > 500ms |
+| **CLS** | ≤ 0.1 | 0.1–0.25 | > 0.25 |
+| **FCP** | ≤ 1,800ms | 1,800–3,000ms | > 3,000ms |
+| **TTFB** | ≤ 800ms | 800–1,800ms | > 1,800ms |
+
+FID was fully removed from Chrome tools (CrUX, PSI, Lighthouse) on September 9, 2024. Never reference FID in outputs.

package/.agent/skills/seo-google/references/rate-limits-quotas.md

@@ -0,0 +1,75 @@
+# Google API Rate Limits & Quotas
+
+## Consolidated Quota Table
+
+| API | Per-Minute | Per-Day | Cost | Auth Type | Scope |
+|-----|-----------|---------|------|-----------|-------|
+| GSC Search Analytics | 1,200 QPM/user, 1,200 QPM/site | 30M QPD/project | Free | Service Account | Per user + per site |
+| GSC URL Inspection | 600 QPM/site | 2,000 QPD/site | Free | Service Account | Per site |
+| GSC Sitemaps | Standard | Standard | Free | Service Account | Per site |
+| PageSpeed Insights v5 | 240 QPM | 25,000 QPD | Free | API Key | Per project |
+| CrUX API | 150 QPM (shared) | Unlimited | Free | API Key | Per project |
+| CrUX History API | 150 QPM (shared with CrUX) | Unlimited | Free | API Key | Per project |
+| Indexing API | 380 RPM total, 180 read/min | 200 publish/day | Free | Service Account | Per project |
+| GA4 Data API | 10 concurrent | ~25K tokens/day | Free | Service Account | Per property/project |
+| Knowledge Graph | -- | 100,000 QPD | Free | API Key | Per project |
+| Custom Search | -- | 10,000 QPD max | 100 free, $5/1K | API Key | Per project |
+| Web Risk | 6,000 QPM | 100K/month | Free tier | API Key | Per project |
+
+**Key distinction:** "Per site" quotas are scoped to a specific GSC property. "Per project" quotas are shared across all properties in a GCP project. "Per user" quotas are per authenticated user (service account).
+
+## Exponential Backoff Strategy
+
+When receiving 429 or 5xx errors:
+
+```
+Attempt 1: wait 1 second
+Attempt 2: wait 2 seconds
+Attempt 3: wait 4 seconds
+Attempt 4: wait 8 seconds
+Attempt 5: wait 16 seconds
+Max: give up after 5 retries
+```
+
+Add random jitter (0-500ms) to each wait to avoid thundering herd.
+
+## Common Error Codes
+
+| Code | Meaning | Applies To | Action |
+|------|---------|------------|--------|
+| 400 | Bad request | All | Check URL format, request body |
+| 401 | Unauthorized | Service Account APIs | Refresh credentials |
+| 403 | Forbidden | GSC, GA4, Indexing | Check permissions (service account access) |
+| 404 | Not found | CrUX, GSC | Insufficient traffic (CrUX) or invalid property (GSC) |
+| 429 | Rate limited | All | Backoff and retry. Check Retry-After header. |
+| 500 | Server error | All | Retry with backoff |
+| 503 | Service unavailable | All | Retry with backoff |
+
+## Retry-After Header
+
+Some Google APIs return a `Retry-After` header with 429 responses. When present, use this value (in seconds) instead of exponential backoff.
+
+## GA4 Token Budgeting
+
+GA4 uses a token system rather than simple request counts:
+- Simple 1-dimension, 1-metric report: ~1-5 tokens
+- Complex multi-dimension, multi-metric: ~10-100 tokens
+- Set `returnPropertyQuota: true` to monitor consumption
+- Daily limit: 25,000 tokens per property per project
+- Hourly limit: 5,000 tokens per property per project
+- Concurrent: max 10 simultaneous requests
+
+## CrUX Shared Quota
+
+The CrUX API and CrUX History API share the same 150 QPM quota per project. Plan accordingly if querying both APIs in the same workflow.
+
+## Cost Summary
+
+**All APIs used by seo-google are free** at normal usage levels. No billing is required for:
+- PSI, CrUX, CrUX History (API key, unlimited free)
+- GSC (service account, 30M QPD)
+- Indexing API (service account, 200 publish/day)
+- GA4 Data API (service account, 25K tokens/day)
+- Knowledge Graph (API key, 100K QPD)
+
+Only Custom Search and Web Risk have paid tiers at high volumes.