Log Ingestion

POST /api/ingest/logs accepts batches of request-log entries from any system that can send JSON. Only AI-relevant entries are stored (known AI crawlers, bot-like agents, and AI-referred human visits); everything else is discarded on arrival. This is the write-side counterpart of crawler events and AI referrals.

Authentication

Create a log-ingest key in the app (AI crawlers, then Install, then Log sources, Webhook tab). Present it as:

X-API-Key: <site_key_id>.<key>

Providers that can only configure a URL (for example Cloudflare Logpush HTTP destinations) can pass the same value as a key= URL parameter instead. Log-ingest keys cannot be used for anything else, and tracking snippet keys cannot submit logs.

Request

{
  "source": "webhook",
  "entries": [
    {
      "timestamp": "2026-08-23T10:00:00Z",
      "method": "GET",
      "url": "/pricing?utm_source=chatgpt.com",
      "status": 200,
      "user_agent": "Mozilla/5.0 ...",
      "client_ip": "203.0.113.9",
      "referer": "https://chatgpt.com/",
      "country": "US"
    }
  ]
}

• Up to 500 entries per batch, 5 MB per request.
• timestamp is ISO 8601 or epoch (seconds or milliseconds). Entries older than 30 days are skipped.
• url may be a path or a full URL; the query string is only used to read utm_source for referral classification.
• client_ip is used for crawler verification and then discarded; only daily aggregates are stored.
• source labels the rows (webhook by default). Managed connections set their own labels.

Response

{ "ok": true, "received": 4, "stored": 3, "discarded": 1, "invalid": 0 }

stored counts AI-relevant entries written, discarded counts entries that matched nothing AI-related, invalid counts entries that could not be processed.

Reading the data back

Log-sourced rows appear in /api/v1/crawler-events and /api/v1/ai-referrals with their ingest_source value, filterable with ?ingest_source=webhook (or cloudflare_worker, vercel, upload, wordpress, beacon).