Axiom

An axiom drain posts to one Axiom dataset’s ingest endpoint. Each record becomes one event with _time, level, message, and the whole Lua record under lua — which Axiom flattens at ingest, so lua.eventName and lua.attributes.* are queryable exactly as the event schema spells them.

Vendor destinations are opened per deployment. Where axiom is not open yet, a create answers 422 DRAIN_TYPE_UNAVAILABLE and the message names the types that are. It may not be enabled on your deployment yet.

Before you begin

An Axiom dataset.
An API token with ingest permission on it.

What to enter

Field	Flag	Value
Name	`--name`	1–64 characters, unique in the organization
Type	`--type axiom`
Endpoint	`--endpoint`	The full ingest URL, ending in the dataset
Token	`--header Authorization`	Enter it as `Bearer <API token>`

The endpoint must name the dataset. https://api.axiom.co/v1/ingest/agent-logs is accepted; https://api.axiom.co alone is refused at create time with 422 DRAIN_VALIDATION_FAILED and field: "endpoint", because there is no dataset to ingest into. The dataset is public configuration, not a credential, so it stays in the stored endpoint and is visible on a read of the drain.

lua drains create \
  --name "Axiom prod" \
  --type axiom \
  --endpoint https://api.axiom.co/v1/ingest/agent-logs \
  --header Authorization \
  --environments production \
  --min-severity info

In CI:

lua drains create --ci --json \
  --name "Axiom prod" --type axiom \
  --endpoint https://api.axiom.co/v1/ingest/agent-logs \
  --header-from-env Authorization=AXIOM_TOKEN

The host must end in .axiom.co. That is a suffix rule, so api.eu.axiom.co is admitted and evil-axiom.co is not — the leading dot is what stops a lookalike domain matching. Anything else answers 422 DRAIN_ENDPOINT_NOT_ALLOWED. The last path segment may contain letters, digits, and . _ ~ % = + - only; anything else is refused rather than interpolated.

How ownership verification works

A vendor preset is reachability-checked, not ownership-verified. lua drains verify posts one batch holding a single lua.drain.test record, and any 2xx from the ingest endpoint is accepted. It proves the dataset exists and the token can write to it. It does not prove you own it. Only a generic HTTPS drain is ownership-verified by a token echo, and only an object-storage drain proves ownership by writing into a bucket.

lua drains verify drn_8b3f21e5c904a7d61f02bb55

A 401 means the token is wrong or lacks ingest permission; a 404 usually means the dataset in the URL does not exist. Verification is limited to 5 attempts per drain per hour. Axiom deliveries are not signed.

What arrives

A JSON array of events:

[
  {
    "_time": "2026-09-12T12:59:57.644Z",
    "level": "error",
    "message": "Ticket lookup failed: upstream timeout",
    "lua": {
      "id": "1789217997644-jtoulxxxq",
      "timestamp": "2026-09-12T12:59:57.644Z",
      "observedTimestamp": "2026-09-12T12:59:59.102Z",
      "eventName": "lua.skill.error",
      "severityNumber": 17,
      "severityText": "ERROR",
      "body": "Ticket lookup failed: upstream timeout",
      "attributes": {
        "lua.source": "skill",
        "lua.primitive.name": "tickets",
        "gen_ai.tool.name": "lookup_tickets",
        "lua.duration_ms": 1841
      }
    }
  }
]

Axiom field	Comes from
`_time`	The record’s `timestamp`, RFC 3339 in UTC
`level`	The severity, lower-cased: `debug`, `info`, `warn`, `error`
`message`	The record’s `body`, or its `eventName` when there is no body
`lua`	The whole record, unflattened — Axiom flattens it at ingest

_time is the one reserved field, and sending it is what makes a replayed backlog readable: without it Axiom stamps ingestion time, and a batch delivered after a pause would all land at the same instant. A timestamp that does not parse is passed through untouched rather than replaced with “now” — Lua does not assert a time it never measured. level and message are not reserved, but they are what Axiom’s own dashboards look for.

Useful queries

['agent-logs'] | where ['lua.eventName'] == 'lua.skill.error'
['agent-logs'] | where level == 'error' | summarize count() by bin_auto(_time), ['lua.attributes.lua.source']
['agent-logs'] | where ['lua.attributes.gen_ai.tool.name'] == 'lookup_tickets'
['agent-logs'] | where ['lua.eventName'] == 'lua.drain.heartbeat'

Caps

Cap	Value
Events per request	10,000 — the vendor’s own ceiling; the byte cap binds first in practice
Uncompressed bytes per request	448 KiB
Bytes per event	256 KiB
Compression	`gzip`, always
Retried	`408`, `429`, and every `5xx`
Terminal	Every `3xx`, and every other `4xx`

A record over 256 KiB has its body cut and suffixed ... [truncated by lua] rather than being dropped.

The 448 KiB batch cap is roughly half what the other vendor presets use, and deliberately so: an Axiom event carries the body twice — once as message, once inside the nested record — so a full batch encodes to about 1.9× the bytes the cap was checked against. Halving the cap is what keeps a full batch inside a 1 MiB request.

Prefer OTLP? Use an `otlp` drain

Axiom accepts OTLP directly, and an otlp drain reaches it with no preset of its own: point it at Axiom’s OTLP logs endpoint and add X-Axiom-Dataset as a drain header.

lua drains create \
  --name "Axiom via OTLP" \
  --type otlp \
  --endpoint https://api.axiom.co/v1/traces \
  --header Authorization \
  --header X-Axiom-Dataset

The trade-off is the one on OpenTelemetry: OTLP gives you resource attributes promoted onto every record and a standard wire format, and it gives up the flat lua.* shape the native preset produces.

Test the token with curl

AXIOM_URL='https://api.axiom.co/v1/ingest/agent-logs'
AXIOM_TOKEN='<your Axiom API token>'

curl -sS -i -X POST "$AXIOM_URL" \
  -H "Authorization: Bearer $AXIOM_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "_time": "2026-09-12T12:59:57.644Z",
      "level": "info",
      "message": "Lua drain connectivity test",
      "lua": { "id": "probe-0001", "eventName": "lua.drain.test", "severityText": "INFO" }
    }
  ]'

200 means accepted; the event shows up in the dataset within a few seconds. Then:

lua drains test drn_8b3f21e5c904a7d61f02bb55

If it isn’t working

422 DRAIN_VALIDATION_FAILED on the endpoint

The URL does not end in a dataset. It must be the full ingest URL: https://api.axiom.co/v1/ingest/<dataset>.

422 DRAIN_ENDPOINT_NOT_ALLOWED

The host does not end in .axiom.co. A self-hosted proxy in front of Axiom is not accepted by this type — use a generic HTTPS drain for that, which is signed as well.

Everything lands at the same timestamp

That is ingestion time, which means _time was not read. Lua always sends it, so check for an ingest transform in Axiom that overwrites it.

401 on every delivery

The stored value must read Bearer <token>, prefix included — the header is sent verbatim. Re-enter it with lua drains update <id> --header Authorization.

Next steps

Event schema

What every field under lua means.

OpenTelemetry

The OTLP alternative, and what it trades.

Protecting your destination

What verification does and does not prove.

lua drains

Every verb and flag.

Get started

Concepts

Build

Channels

Integrations

Devices

Ship and operate

Ship logs to your stack

Marketplace

Build with AI

Examples

What to enter

How ownership verification works

What arrives

Useful queries

Caps

Prefer OTLP? Use an `otlp` drain

Test the token with curl

If it isn’t working

Next steps

Event schema

OpenTelemetry

Protecting your destination

lua drains

​What to enter

​How ownership verification works

​What arrives

​Useful queries

​Caps

​Prefer OTLP? Use an otlp drain

​Test the token with curl

​If it isn’t working

​Next steps

Event schema

OpenTelemetry

Protecting your destination

lua drains

What to enter

How ownership verification works

What arrives

Useful queries

Caps

Prefer OTLP? Use an `otlp` drain

Test the token with curl

If it isn’t working

Next steps