API — Log Ingestion
Copy the prompt and paste it into Cursor, Claude Code, Codex, Copilot… — it does the install for you.
POST https://logs.withmaya.ai/v1/logs
Receives access-log records, keeps AI-agent traffic and shows it in LLM Site Visibility. Real-time streams and batch exports use this same endpoint. See Real-time Log Streaming for platform setup.
Authentication
Credentials go in request headers. Copy all three values from the Streaming setup in LLM Site Visibility. Rotating the key there invalidates the old one.
| Header | Required | Value |
|---|---|---|
x-maya-signal-project | Yes | Project ID (prj_...) |
x-maya-signal-key | Yes | Write key (msig_live_...) |
x-maya-signal-source | Yes | Source ID (src_...) |
x-maya-signal-zone | No | Your domain. Otherwise taken from each record's host. |
Content-Type | Yes | application/x-ndjson or application/json |
Request body
Send one of these:
- Newline-delimited JSON, one record per line
- A JSON array of records
{ "records": [...] }
{"timestamp":"2026-04-22T13:15:42Z","user_agent":"Mozilla/5.0 (compatible; GPTBot/1.2; +https://openai.com/gptbot)","request_method":"GET","request_path":"/products/super-widget","status_code":200,"response_bytes":48329,"referrer":"","host":"www.example.com"}
{"timestamp":"2026-04-22T13:16:01Z","user_agent":"PerplexityBot/1.0","request_method":"GET","request_path":"/pricing","status_code":200,"response_bytes":62104,"referrer":"https://www.perplexity.ai/","host":"www.example.com"}Fields
Each field accepts several names, so most log formats work unchanged. The names below are the common ones. Unrecognised fields are ignored.
| Field | Required | Accepted names |
|---|---|---|
| Method | Yes | request_method, method, http_method, ClientRequestMethod, cs-method |
| User agent | Yes | user_agent, userAgent, http_user_agent, ClientRequestUserAgent |
| Path | Yes, in practice | request_path, path, url, uri, request_uri, request_url, page_path, ClientRequestURI, cs-uri-stem |
| Status | Recommended | status_code, status, http_status, statusCode, response_code, EdgeResponseStatus, sc-status |
| Host | Recommended | host, http_host, server_name, ClientRequestHost |
| Response size | Recommended | response_bytes, body_bytes_sent, bytes_sent, EdgeResponseBytes, sc-bytes |
| Time | Recommended | timestamp, time, time_iso8601, occurred_at, @timestamp, EdgeStartTimestamp |
| Referrer | Optional | referrer, referer, http_referer, ClientRequestReferer |
| Client IP | Optional | client_ip, ip, remote_addr, ClientIP |
nginx's combined request field ("GET /path HTTP/1.1") also works in place of method and path.
What happens when a field is missing:
- Method or user agent: the record is skipped.
- Path: the record is stored with the path
/, so page reports lose their detail. The response counts these inmissing_url. - Status: the record counts toward total requests but not toward success or errors, so success rate reads 0%. Send the real status rather than a fixed
200, which would report a false 100% and hide errors. - Response size: bandwidth shows as 0.
A raw client IP is used to verify the bot against its operator's published IP ranges, and is then stored only as a hash. client_ip_hash isn't read.
Limits
| Limit | Value |
|---|---|
| Records per request | 5,000 (above this returns 413) |
Split larger files into several requests, and send bodies uncompressed.
Responses
202 Accepted
{
"received": 5000,
"agent_events": 4980,
"forwarded": 4980,
"rejected": 0,
"missing_url": 0
}| Field | Meaning |
|---|---|
received | Records parsed from the body |
agent_events | Records identified as AI agents. Other traffic is dropped. |
forwarded | Agent records accepted |
rejected | Agent records refused downstream |
missing_url | Records with no recognised path field |
A 202 doesn't confirm delivery. A wrong key also returns 202, with every agent record counted in rejected. Treat a request as successful only when rejected is 0 and forwarded equals agent_events. A batch with no AI-agent traffic returns agent_events: 0 and forwarded: 0, which is normal.
Records are forwarded in groups of 25, and one record whose host isn't on the project's allowed list rejects its whole group. If rejected is above 0, check the key first, then the hostnames in the Streaming setup.
Errors
| Status | Body | Fix |
|---|---|---|
400 | invalid_body or no_records | Check that the body is valid JSON and not empty. |
401 | missing_credentials | Send the project and key headers. |
413 | too_many_records | Send at most 5,000 records per request. |
Retries
The endpoint doesn't deduplicate. Sending the same records twice counts them twice, so retry only requests that failed with no 202 response.
Test mode
There is no test mode. To validate an integration, send a small sample and check the response. Sample records appear in your dashboard.
Example — curl
curl -X POST https://logs.withmaya.ai/v1/logs \
-H "x-maya-signal-project: $MAYA_SIGNAL_PROJECT" \
-H "x-maya-signal-key: $MAYA_SIGNAL_KEY" \
-H "x-maya-signal-source: $MAYA_SIGNAL_SOURCE" \
-H "Content-Type: application/x-ndjson" \
--data-binary @export-2026-04-22.ndjsonExample — Node.js
import { readFile } from "node:fs/promises";
const body = await readFile("./export-2026-04-22.ndjson");
const res = await fetch("https://logs.withmaya.ai/v1/logs", {
method: "POST",
headers: {
"x-maya-signal-project": process.env.MAYA_SIGNAL_PROJECT!,
"x-maya-signal-key": process.env.MAYA_SIGNAL_KEY!,
"x-maya-signal-source": process.env.MAYA_SIGNAL_SOURCE!,
"Content-Type": "application/x-ndjson",
},
body,
});
const result = await res.json();
if (!res.ok || result.forwarded < result.agent_events || result.rejected > 0) {
throw new Error(`Maya ingestion ${res.status}: ${JSON.stringify(result)}`);
}
console.log(result);Example — Python
import os
import requests
with open("export-2026-04-22.ndjson", "rb") as f:
body = f.read()
res = requests.post(
"https://logs.withmaya.ai/v1/logs",
headers={
"x-maya-signal-project": os.environ["MAYA_SIGNAL_PROJECT"],
"x-maya-signal-key": os.environ["MAYA_SIGNAL_KEY"],
"x-maya-signal-source": os.environ["MAYA_SIGNAL_SOURCE"],
"Content-Type": "application/x-ndjson",
},
data=body,
timeout=60,
)
result = res.json()
if not res.ok or result.get("forwarded", 0) < result.get("agent_events", 0) or result.get("rejected", 0) > 0:
raise RuntimeError(f"Maya ingestion {res.status_code}: {result}")
print(result)Example — PowerShell
$body = Get-Content 'D:\maya\export-2026-04-22.ndjson' -Raw
$result = Invoke-RestMethod `
-Uri 'https://logs.withmaya.ai/v1/logs' `
-Method Post `
-Body $body `
-ContentType 'application/x-ndjson' `
-Headers @{
'x-maya-signal-project' = $env:MAYA_SIGNAL_PROJECT
'x-maya-signal-key' = $env:MAYA_SIGNAL_KEY
'x-maya-signal-source' = $env:MAYA_SIGNAL_SOURCE
}
if ($result.forwarded -lt $result.agent_events -or $result.rejected -gt 0) {
throw "Maya ingestion problem: $($result | ConvertTo-Json -Compress)"
}