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

​
Base endpoint

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: 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 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

The batch was published to the pipeline. This is success. It acknowledges receipt, not storage; data becomes queryable a few seconds later.
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.
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.
The signal is not enabled for your account, or the source address is not permitted.
The body exceeded a size cap. See limits.
A rate limit was hit. A Retry-After header gives the wait in seconds.
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

  • 50 MB maximum request body.

​
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.