Skip to content
Maple Docs
Open app

Ingest API

The OTLP ingest endpoint: paths, authentication, content types, compression, request limits, status codes, and how to retry.

Every signal reaches Maple through one OTLP gateway. Any OpenTelemetry SDK or Collector that exports OTLP over HTTP or gRPC works without a Maple-specific exporter.

Base URLhttps://ingest.maple.dev, or your region’s ingest host
ProtocolOTLP over HTTP (POST), or OTLP over gRPC on port 443 (see gRPC)
AuthAuthorization: Bearer maple_pk_… (or maple_sk_…, or a maple_src_… source token)
EncodingsProtobuf (recommended) or JSON, optionally gzip
Max body20 MiB per request, measured on the compressed body; 160 MiB once decompressed
Request time30 seconds per request

Endpoints

PathPayload
POST /v1/tracesOTLP ExportTraceServiceRequest
POST /v1/logsOTLP ExportLogsServiceRequest
POST /v1/metricsOTLP ExportMetricsServiceRequest
POST /v1/prometheus/writePrometheus remote write 1.0
POST /v1/eventsProduct events
POST /v1/sessionReplays/*Session replay chunks, sent by the browser SDK
POST /v1/sessionEventsSession timeline events, sent by the browser SDK

Use the ingest host of your organization’s region. A key from one region is rejected by the other. A standard exporter appends the signal path itself:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.maple.dev"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer maple_pk_…"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"   # or grpc

gRPC

The same host also serves the OTLP gRPC services for traces, logs and metrics (opentelemetry.proto.collector.{trace,logs,metrics}.v1.*Service/Export). Point a gRPC exporter at the base URL with no port, https://ingest.maple.dev, and it connects over TLS on port 443. Do not add port 4317. Send the key as authorization: Bearer maple_pk_… metadata (or x-maple-ingest-key); OTEL_EXPORTER_OTLP_HEADERS sets it for you. Messages may be gzip-compressed.

export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.maple.dev"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer maple_pk_…"
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"

Failures come back as gRPC status codes instead of HTTP ones: an invalid key is UNAUTHENTICATED (16), a signal the source token does not allow is PERMISSION_DENIED (7), rate limits are RESOURCE_EXHAUSTED (8), a malformed request is INVALID_ARGUMENT (3), an unsupported grpc-encoding is UNIMPLEMENTED (12), and server-side failures are UNAVAILABLE (14), which exporters retry. The status message says what went wrong.

Product events, session replays and session events are HTTP only.

Authentication

Send your ingest key on every request, either as a Bearer token or in the x-maple-ingest-key header. The Bearer prefix is case-insensitive.

Authorization: Bearer maple_pk_…
x-maple-ingest-key: maple_pk_…

Ingest keys can only send data, and each belongs to one organization. Use the public key (maple_pk_…) in browsers and mobile apps, where it ships to end users, and the private key (maple_sk_…) on servers. Find both under Settings → Ingestion in the dashboard. Authentication explains the difference. A source you connect under Sources can instead use its own source token (maple_src_…), which may allow only some signals, expire, be paused or carry a rate limit.

The literal key MAPLE_TEST is accepted and returns 200, but the data is discarded. Use it in CI or example code where you want the exporter to run without sending anything.

Content types and compression

Content-TypeRead as
application/x-protobuf, application/protobufOTLP protobuf
application/octet-streamOTLP protobuf
anything containing json (application/json)OTLP JSON
header missingOTLP protobuf
anything else415

For compression, send Content-Encoding: gzip. Omit the header (or send identity) for an uncompressed body. gzip is the only compression supported. zstd, deflate and br are rejected with 415, so set your exporter’s compression to gzip or none.

/v1/prometheus/write is the exception: its body is always a snappy-compressed prometheus.WriteRequest, as the remote write protocol defines. It also reads the ingest key from the basic-auth password, for senders that authenticate that way.

Browsers

The gateway answers CORS preflights from any origin, so a browser can export directly. Allowed request headers are Authorization, Content-Type, Content-Encoding, x-maple-ingest-key and the x-maple-* headers the browser SDK sends. No response headers are exposed to scripts, so browser code cannot read Retry-After; back off on a fixed schedule instead.

Status codes

Errors carry a JSON body with the same envelope as the Maple API:

{
	"error": {
		"_tag": "@maple/ingest/OrgQueueThrottled",
		"type": "rate_limit_error",
		"code": "ingest_queue_throttled",
		"title": "Ingest queue full for this org",
		"message": "This org's ingest queue is at capacity. No data was written; resend this batch after the suggested delay.",
		"retryable": true,
		"recovery": "retry",
		"retry_after_seconds": 1
	}
}
FieldMeaning
_tagThe exact failure, stable across releases. Branch on this
typeThe status family: invalid_request_error, authentication_error, permission_error, payment_error, rate_limit_error or api_error (5xx)
codeThe short code in the table below
title, messageHuman-readable text
retryableWhether resending the same batch can succeed
recoveryfix_request, reauthenticate, retry or contact_support
retry_after_secondsPresent when a retry makes sense. The same value is in the Retry-After header

A successful request returns 200: the batch is accepted and durably queued. Checks run roughly in the order below, so a request fails on the first one it trips.

StatusCodeTagCauseRetry?
401ingest_unauthorized@maple/ingest/UnauthorizedMissing, malformed or unknown ingest key, or a key sent to the other region’s ingestNo. Fix the key
401ingest_key_expired@maple/ingest/IngestKeyExpiredThe source token is past its expiryNo. Issue a new token
403ingest_signal_not_allowed@maple/ingest/SignalNotAllowedThe source token does not allow this signalNo
429ingest_key_rate_limited@maple/ingest/IngestKeyRateLimitedThe source token is over its requests-per-second limitYes, after 1 s
429ingest_rate_limited@maple/ingest/RateLimitedMore than 1,000 requests in flight for your organizationYes, after 1 s
413ingest_payload_too_large@maple/ingest/PayloadTooLargeBody over 20 MiB compressed, or over 160 MiB once decompressedNo. Send smaller batches
413ingest_row_expansion@maple/ingest/RowExpansionThe stored rows would be more than 512 times the decompressed batch (see Batching)No. Shorten shared attributes
413ingest_rows_exceed_queue@maple/ingest/RowsExceedQueueThe stored rows would be more than your organization’s ingest queue holds (1 GiB)No. Send smaller batches
415ingest_unsupported_media_type@maple/ingest/UnsupportedMediaTypeUnknown Content-Type or Content-EncodingNo. Fix the exporter config
400ingest_bad_request@maple/ingest/BadRequestInvalid gzip, a body that is not valid OTLP, or a malformed product event, session event or replay headerNo
400ingest_replay_body_not_gzip@maple/ingest/ReplayBodyNotGzipA session replay chunk that is not a gzip streamNo
402ingest_plan_limit_reached@maple/ingest/PlanLimitReachedNo active subscription, or the plan’s limit is reachedNo. Check Settings → Billing & usage
429ingest_queue_throttled@maple/ingest/OrgQueueThrottledYour organization’s ingest queue is full. Nothing was writtenYes, after 1 s
429ingest_export_lane_full@maple/ingest/ExportLaneBackpressureThe write path for your organization is backed up. Nothing was writtenYes, after 2 s
503ingest_unavailable@maple/ingest/ServiceUnavailableKey lookup or another dependency is temporarily unavailableYes, after 5 s
503ingest_queue_unavailable@maple/ingest/QueueUnavailableThe batch could not be written to the durable queue (see Batching for large batches)Yes, after 5 s
503ingest_collector_unavailable@maple/ingest/CollectorUnavailableAn upstream collector failed or its response could not be readYes, after 5 s
503ingest_request_timeout@maple/ingest/RequestTimeoutThe request took longer than 30 secondsYes, after 5 s
503ingest_decode_busy@maple/ingest/DecodeBusyThe gateway is busy with other requests. Nothing was writtenYes, after 1 s
503ingest_encode_failed@maple/ingest/PayloadEncodeFailedThe batch could not be encoded for storage. Resending the same batch fails the same wayNo. Contact support
500ingest_internal_error@maple/ingest/InternalErrorUnexpected gateway errorNo. Contact support

OpenTelemetry SDKs and the Collector already retry 429 and 503 with backoff, and drop on other 4xx codes. That is the right behavior for every code above except ingest_encode_failed, which an exporter retries even though it cannot succeed.

Batching

A request is limited by its compressed size (20 MiB), not its span or record count. The default batch sizes of the OpenTelemetry SDKs (512 spans or log records per export) and of the Collector’s batch processor (8,192 items) stay far below that. If you raise them and a batch reaches the limit, the gateway answers 413 and the exporter drops the whole batch.

Every stored row carries its resource and scope attributes, so a batch is stored as several times its decompressed size: 3 to 13 times for typical telemetry, and up to about 200 times when a long resource attribute, such as a JVM command line, sits on many small items. The gateway builds and stores the rows in pieces, so a large batch needs no more memory than a small one. Two limits still apply to the rows, and both are checked before anything is stored. A batch whose rows would come to more than 512 times its decompressed size is refused with 413 ingest_row_expansion; shorten the shared attributes or send fewer items per resource. A self-hosted gateway sets this ratio with INGEST_MAX_ROW_EXPANSION (default 512, 0 turns it off). A batch whose rows are more than your organization’s ingest queue holds (1 GiB, INGEST_ORG_QUEUE_MAX_BYTES when self-hosted) is refused with 413 ingest_rows_exceed_queue; send smaller batches. A self-hosted gateway also refuses rows larger than one write-ahead log lane, INGEST_QUEUE_MAX_BYTES divided by twice the shard count, which can be the lower limit on a host with many CPUs.

The queue room for a batch’s rows is reserved before its first piece is stored, so 429 and ingest_decode_busy mean nothing was written. A batch stored in several pieces can still fail part way through if the durable queue fails a write or the request times out. The error then says how many pieces were already stored; those are kept, so resending the batch stores them a second time.