Endpoints and errors

Every ingest path, every status code the receiver returns, the rate limits and the size caps — the page to open when a request is being rejected.

Reference for the ingest surface. If a request is being rejected and you want to know why, start with status codes.

Base endpoint

Deployment	Base endpoint
aiAxonIQ Cloud	https://app.aiaxoniq.com/otlp
Self-hosted behind the bundled nginx	https://app.<your-domain>/otlp

Both forms carry the /otlp prefix because nginx serves OTLP under it and strips it before forwarding, so the receiver still sees /v1/logs. Dropping the prefix is the most common setup mistake: the request reaches the dashboard instead of the receiver and comes back as an HTML 404 rather than an ingest error.

Get Started in the dashboard shows the exact base endpoint for your deployment next to a license key you create there, with copy buttons, and then watches for your first records. Where these pages write $OIQ_ENDPOINT, that page has the real value.

Paths

Over HTTP:

Method	Path	Purpose
POST	/v1/logs	OTLP logs
POST	/v1/metrics	OTLP metrics
POST	/v1/traces	OTLP traces
POST	/api/v1/prom/write	Prometheus remote-write
GET	/health	Liveness — always 200 if the process is up
GET	/readyz	Readiness — 200 when the pipeline is reachable, 503 when not
GET	/metrics	The receiver’s own Prometheus metrics

Over gRPC, on port 4317: the standard OTLP logs, metrics and trace services.

gRPC is not exposed on aiAxonIQ Cloud — the hosted deployment serves OTLP over HTTP only, and port 4317 refuses connections. It is reachable only on a self-hosted deployment whose reverse proxy has been configured to carry gRPC. See OTLP over gRPC.

Where both are served, they accept the same dashboard-issued key and enforce the same rate limits, quotas and per-signal entitlements — the only difference is that gRPC metadata keys are lower-case, so the header is x-license-key.

/health is a static check on the process only; it does not test dependencies. Use /readyz if you want a check that fails when the pipeline behind the receiver is unreachable. Wiring a load balancer to /health expecting it to drain an unhealthy receiver will not do what you want.

Authentication

Send your license key one of two ways:

X-License-Key: oiq_4f3c2b1a9e8d7c6b5a4f3e2d1c0b9a8e

Authorization: Bearer oiq_4f3c2b1a9e8d7c6b5a4f3e2d1c0b9a8e

X-License-Key takes precedence if both are present. Header names are case-insensitive; the key value is not.

One reason to prefer the X-License-Key header. Rate limiting buckets requests by that header’s value, falling back to source IP when it is absent. Authenticating with Authorization: Bearer therefore shares a rate-limit bucket with everything else from the same address. If several services egress through one NAT gateway, they will collectively hit a limit that the per-key form would have kept separate.

Status codes

202 Accepted — success

The batch was published to the pipeline. This is success. It acknowledges receipt, not storage; data becomes queryable a few seconds later.

400 Bad Request — the payload did not decode

Causes: malformed protobuf, a body that does not match the declared content type, or a payload that decodes but violates the OTLP schema.

Rejected payloads are copied to a dead-letter queue, so they are recoverable by an operator.

401 Unauthorized — the key was not accepted

One of:

• No key supplied — the message names both accepted headers.
• Malformed key — not oiq_-prefixed, or shorter than 20 characters.
• Invalid or revoked key.

A 401 does not always mean your key is wrong. If the receiver cannot reach the service that validates keys, validation fails closed and returns the same 401 as a genuinely invalid key. A sudden 401 across every service at once, with a key you have not changed, is far more likely to be a validation outage than a credential problem. Check /readyz before regenerating keys.

403 Forbidden — valid key, disallowed request

The signal is not enabled for your account, or the source address is not permitted.

413 Payload Too Large

The body exceeded a size cap. See limits.

429 Too Many Requests

A rate limit was hit. A Retry-After header gives the wait in seconds.

500 / 502 / 503 — retryable

The receiver could not publish to the pipeline. OpenTelemetry SDKs and Prometheus remote-write both retry these with backoff.

Rate limits

Three limits apply to authenticated HTTP ingest:

• 200 requests per second per account, with a burst allowance of 400. Exceeding it returns 429 with Retry-After: 1.
• 10,000 requests per minute per account. Exceeding it returns 429 with Retry-After: 60.
• A global per-key limit, which also returns 429.

The per-second limit does not apply to Prometheus remote-write; the per-minute limit does.

These are limits on requests, not on records. Batching is therefore the correct response to hitting them — an SDK exporting 500 spans in one request uses one of your 200 per second, not 500. If you are being rate-limited, look at your exporter’s batch settings before asking for a limit increase.

Limits and caps

General ingest

• 50 MB maximum request body.

Prometheus remote-write

Tighter caps than general ingest:

• 8 MB compressed body
• 64 MB decompressed
• 10,000 timeseries per request
• 100,000 total samples per request
• 128 labels per series
• 1,024 bytes per label name or value

Exceeding the decompressed cap returns 413; exceeding the series, sample or label caps returns 400.

Encodings

OTLP/HTTP accepts:

• application/json
• application/x-protobuf
• application/octet-stream — treated as protobuf

Request bodies may be gzip, deflate or brotli compressed. An unsupported Content-Encoding returns 415; a body that fails to decompress returns 400.

Prometheus remote-write is the exception: it expects snappy-compressed protobuf and has HTTP-level decompression disabled, so gzip on top of it will fail. Leave Prometheus’s compression settings alone and it will do the right thing.

Next

Send data with OpenTelemetry

Endpoints, headers and a first request.

Prometheus remote-write

Ship from an existing Prometheus server.