MayaBook a demo
Maya

API — Log Ingestion

Audience: Engineering, AI agents performing integrationUpdated 2026-11-05
Claude CodeCodexGitHub Copilot
Set this up with your coding agent

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.

HeaderRequiredValue
x-maya-signal-projectYesProject ID (prj_...)
x-maya-signal-keyYesWrite key (msig_live_...)
x-maya-signal-sourceYesSource ID (src_...)
x-maya-signal-zoneNoYour domain. Otherwise taken from each record's host.
Content-TypeYesapplication/x-ndjson or application/json

Request body

Send one of these:

  • Newline-delimited JSON, one record per line
  • A JSON array of records
  • { "records": [...] }
JSON
{"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.

FieldRequiredAccepted names
MethodYesrequest_method, method, http_method, ClientRequestMethod, cs-method
User agentYesuser_agent, userAgent, http_user_agent, ClientRequestUserAgent
PathYes, in practicerequest_path, path, url, uri, request_uri, request_url, page_path, ClientRequestURI, cs-uri-stem
StatusRecommendedstatus_code, status, http_status, statusCode, response_code, EdgeResponseStatus, sc-status
HostRecommendedhost, http_host, server_name, ClientRequestHost
Response sizeRecommendedresponse_bytes, body_bytes_sent, bytes_sent, EdgeResponseBytes, sc-bytes
TimeRecommendedtimestamp, time, time_iso8601, occurred_at, @timestamp, EdgeStartTimestamp
ReferrerOptionalreferrer, referer, http_referer, ClientRequestReferer
Client IPOptionalclient_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 in missing_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

LimitValue
Records per request5,000 (above this returns 413)

Split larger files into several requests, and send bodies uncompressed.

Responses

202 Accepted

JSON
{
  "received": 5000,
  "agent_events": 4980,
  "forwarded": 4980,
  "rejected": 0,
  "missing_url": 0
}
FieldMeaning
receivedRecords parsed from the body
agent_eventsRecords identified as AI agents. Other traffic is dropped.
forwardedAgent records accepted
rejectedAgent records refused downstream
missing_urlRecords 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

StatusBodyFix
400invalid_body or no_recordsCheck that the body is valid JSON and not empty.
401missing_credentialsSend the project and key headers.
413too_many_recordsSend 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

Bash
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.ndjson

Example — Node.js

TypeScript
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

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

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)"
}