Raw events API

The raw events API accepts request logs from any source: your own web server, a CDN without a managed export, or a script replaying historical logs. Events land in the same AI traffic metric as every other collector, with AI crawler and agent classification handled on our side. On Cloudflare Enterprise? Cloudflare Logpush streams the same data with zero ongoing work.

Before you start

You need a The Prompting Company API key (organization or service-account key) from Settings → API Keys.

Send events

POST a JSON array (a single object also works), plain or gzipped, to https://logs.promptingco.com/v1/events/raw. Authenticate with either an X-API-Key header or Authorization: Bearer.

curl -X POST "https://logs.promptingco.com/v1/events/raw" \
  -H "X-API-Key: $TPC_API_KEY" \
  -H "Content-Type: application/json" \
  --data '[
    {
      "timestamp": "2026-08-11T12:00:00.000Z",
      "status_code": 200,
      "request_method": "GET",
      "request_path": "/pricing",
      "query_string": "ref=x",
      "content_type": "text/html",
      "client_ip": "203.0.113.7",
      "hostname": "example.com",
      "user_agent": "Mozilla/5.0 ...",
      "referrer": "https://www.google.com"
    }
  ]'

Field	Required	Notes
`hostname`	yes	Events without it are counted as skipped
`timestamp`	no	ISO 8601 or unix seconds/millis/nanos; defaults to arrival time
`request_path`	no	Defaults to `/`; may include the query string inline (`/pricing?ref=x`)
`query_string`	no	Alternative to inlining the query in `request_path`
`user_agent`, `client_ip`, `request_method`, `status_code`, `content_type`, `referrer`	no	Recommended — user agent and client IP drive AI classification

Requests can be up to 64 MB (compressed and decompressed). Batch as many events per request as fits.

Responses

Status	Meaning
`200`	Batch stored. Body reports `{"ok": true, "received": N, "ingested": N, "skipped": N}`
`401`	Missing or invalid API key
`429`	Key verification was rate limited — retry shortly
`400`	Body could not be decoded or parsed as JSON
`413`	Decompressed body too large — send smaller batches
`503`	Temporary ingestion outage — retry the batch

Delivery is at-least-once: retry the whole batch after a 503, and occasional duplicates are expected and tolerated by the traffic metrics.

Verify it’s working

curl -s -X POST "https://logs.promptingco.com/v1/events/raw" \
  -H "X-API-Key: $TPC_API_KEY" \
  -H "Content-Type: application/json" \
  --data '[{"hostname": "example.com", "request_path": "/", "user_agent": "GPTBot/1.2", "client_ip": "203.0.113.7"}]'

A 200 with "ingested": 1 confirms the pipeline, and the visit appears in your AI traffic dashboard shortly after.

Get started

Dashboard overview

Content publishing

Analytics

Agent experience

Before you start

Send events

Responses

Verify it’s working

​Before you start

​Send events

​Responses

​Verify it’s working

Before you start

Send events

Responses

Verify it’s working