Overview

The Ingestion API is the write side of Metrana: it creates runs and records everything logged against them — attributes, metric series, reinforcement-learning data and agentic traces. The Python SDK is built on it; use the API directly when you are logging from another language, bridging an existing system into Metrana, or need control the SDK does not give you.

Endpoints

Every Metrana deployment serves the API from the same host as the portal. For Metrana Cloud that is app.metrana.ai; a self-hosted deployment uses its own hostname — the one your API token was issued by (see Authentication).

Transport	Address	Notes
gRPC	app.metrana.ai:443 (TLS)	Service metrana_protobuf.ingestion.v1.svc.IngestService. Serves every RPC.
REST	https://app.metrana.ai/api/ingest/v1/...	JSON over HTTP POST. Serves the unary RPCs only.

Both transports run the same validation and produce the same data. See Transports and encoding for the JSON mapping and gRPC details.

Two ways to write data

The API offers two write paths. Pick one per writer process; both land in the same run.

Request/response (CreateRun + UpdateRuns) — create the run once, then send batches of updates. Each call is independent, works over both gRPC and REST, and is the easiest to integrate. Use it for moderate volumes: scripts, evaluation jobs, backfills, bridges from other systems.

Streaming (InitializeRunLogging + UpdateRunStream) — a handshake that registers your process as a logger on the run and reports what the run already holds, followed by one long-lived bidirectional stream. Series are declared once per stream and then addressed by a numeric id, so each update is much smaller. This is what the SDK uses; choose it for high-throughput training loops and many-environment RL. gRPC only. See Streaming ingestion.

Agentic traces have their own RPCs: UpdateTraces, available on both transports, and the long-lived UpdateTracesStream for a process that traces continuously — see Agentic traces.

The RPCs at a glance

RPC	REST route	Purpose
CreateRun	POST /api/ingest/v1/runs	Create a run (and optionally its project and experiment).
UpdateRuns	POST /api/ingest/v1/runs:update	Append attributes, series points and RL data to one or more runs.
InitializeRunLogging	—	Register a streaming logger on a run, creating the run if needed.
UpdateRunStream	—	Stream updates for one run after InitializeRunLogging.
UpdateTraces	POST /api/ingest/v1/traces:update	Record agentic trace and span open/close events.
UpdateTracesStream	—	Stream trace updates over one long-lived connection, acknowledged in order.
CheckOpStatuses	POST /api/ingest/v1/operations:check	Reserved for operation tracking; see the note below.

Operation ids

Responses carry an operation_id field and CheckOpStatuses is defined for polling it, but operation tracking is not implemented yet: operation_id is returned empty and CheckOpStatuses returns an empty map. Treat a successful response as “accepted”: the data has passed validation and is queued, and becomes visible to queries shortly after.

Accepted means durable, not yet visible

Ingestion is part synchronous, part asynchronous. Everything that can be checked up front — authentication, workspace access, names, limits, the shape of every point — is checked before the call returns, so an error response means nothing from that request was applied. A success response means the data was accepted into the ingestion pipeline; it is processed in the background and appears in queries and the portal a moment later.

Writes are at-least-once: if you are unsure whether a request landed (a timeout, a dropped connection), send it again. Re-sent points are deduplicated or overwrite themselves, as described in Logging metrics and attributes.

Where to next

• Authentication — turn your API token into a bearer token.
• Quickstart — create a run and log to it with curl.
• RPC reference — every request and response field.