Set up
1
Create the source
In Agent Analytics, select Connect source, choose Custom HTTP / NDJSON and select Generate credentials.
2
Store the credentials
Copy the token (
aa_live_…) and the endpoint URL into your secret store. The token is shown once.3
Send a test delivery
Run the
curl command the wizard shows. It sets x-agent-analytics-test: 1, so the record is classified and answered but not stored.4
Start sending
Point your sender at the endpoint and select Check now in the wizard.
Request
Authentication
Send the source token in theAuthorization header as Bearer <token>. The token is accepted only in this header, never in the query string, because query strings end up in access logs and browser history.
The endpoint is for server-to-server calls. It sends no CORS headers, so browsers refuse to call it. Never put the token in page-side JavaScript.
Body formats
The body’s shape decides how it’s parsed;Content-Type is only used to force NDJSON.
A malformed line or array element is counted as
invalid_record; the rest of the batch is still processed.
Compression
SendContent-Encoding: gzip or no compression. Any other encoding returns 415.
Limits
Batch your records. One request per log line will hit the delivery limit on a busy site.
Record fields
Each record describes one HTTP request.host and path are required; everything else improves what you can measure.
Hostname the visitor requested, for example
www.example.com. Must be the source’s domain or a subdomain of it.Request path. A full URL is accepted too (
url is an alias). The query string and fragment are always stripped.The visitor’s
User-Agent. Without it, no record can be recognized as an AI agent. Alias: userAgent.The visitor’s IP address (IPv4 or IPv6). Used only to verify the agent, then discarded. Without it, every event is unverified. Alias:
clientIp.When the request happened: an ISO 8601 timestamp, or a Unix epoch in seconds or milliseconds. Alias:
timestamp. If you leave it out, the arrival time is used.Your unique request ID. Strongly recommended: with it, the same request keeps the same
event_id in any later delivery and is stored only once. Without it, a record is identified by its position in the delivery, so resending an identical delivery is still stored once, but the same record sent inside a different batch is stored again.Example
Response
A processed delivery answers202 Accepted. Every record is accounted for exactly once: received = accepted + duplicates + dropped.
Records that repeat another record in the same delivery. A record resent in a later delivery is counted there as
accepted again, but it keeps its event_id and is stored only once.Seconds between the newest accepted record and its arrival.
null when nothing was accepted.One entry per record, by
position (line number for NDJSON, array index for arrays, 0 for a single object), with outcome accepted, duplicate or dropped, and the event_id or reason.accepted, test for a test delivery, or deferred when the events were received and will appear shortly. In every case you don’t need to resend.id, produces the same event_id, so a retry doesn’t create a second event.
Drop reasons
Errors
Retry on
429 and 503 after the Retry-After header when present. Don’t retry 400, 401, 404, 413 or 415 without fixing the request.
Test deliveries
Addx-agent-analytics-test: 1 (or true) to any delivery. It’s authenticated, rate-limited and host-checked like a real one, and the 202 response shows the outcome for every record, but nothing is stored or counted toward your quota. A test delivery also moves a new source to Connected, waiting for the first agent visit.
Example senders
Next steps
Log file import
Upload a log export instead of streaming.
Troubleshooting
Read a receipt and fix the most common drops.