Service endpoints

The SDK talks to three separate Metrana services, each with its own endpoint and its own public default:

Service	Used by	Default
Ingestion	init(), every log call, close(), replay_spool(), metrana migrate	https://ingestion.metrana.ai
Artifacts	artifact functions, video tags and events, rendering uploads	https://artifacts.metrana.ai
Query	QueryClient	https://query.metrana.ai

All three are configurable, so a self-hosted or staging deployment needs no code changes beyond the endpoint itself.

Precedence

Each endpoint resolves in the same order — the first value that is set wins:

1. The explicit argument on the call that opens the connection: ingestion_url on init(), base_url on an artifact or video function, query_url on QueryClient.
2. The init() argument for that service (ingestion_url, artifact_api_url, query_api_url), which applies process-wide for the lifetime of the run.
3. The environment variable (METRANA_INGESTION_URL, METRANA_ARTIFACT_API_URL, METRANA_QUERY_API_URL).
4. The public default from the table above.

Configuring all three at init()

init() accepts one argument per service, so a single call configures the whole SDK:

import metrana

metrana.init(
    workspace_name="ws",
    project_name="proj",
    run_name="run-001",
    ingestion_url="https://ingestion.internal.example.com",
    artifact_api_url="https://artifacts.internal.example.com",
    query_api_url="https://query.internal.example.com",
)

ingestion_url is used by the logger itself. artifact_api_url is used by rendering uploads and becomes the default base_url for every artifact and video tag / event call that does not pass its own. query_api_url is only a default for a QueryClient built in the same process — the logger never queries.

Configuring all three from the environment

The environment variables cover the same ground without touching code, which is the usual choice for CI or a containerized job:

export METRANA_INGESTION_URL="https://ingestion.internal.example.com"
export METRANA_ARTIFACT_API_URL="https://artifacts.internal.example.com"
export METRANA_QUERY_API_URL="https://query.internal.example.com"

A trailing slash is stripped, and a value that is empty or whitespace is treated as unset. See Environment variables for the full list.

Reading from a different deployment than you wrote to

Reading is a separate client, so it can point somewhere else entirely — an analysis process that never calls init() simply configures QueryClient on its own:

from metrana.query import QueryClient

client = QueryClient(
    workspace_name="ws",
    query_url="https://query.internal.example.com",   # or METRANA_QUERY_API_URL
)

The query endpoint is a gRPC target, so it must be http(s)://host[:port] — a URL carrying a path or a query string is rejected with ConfigError rather than silently connecting somewhere else.

Migrating into a different deployment

The metrana migrate CLI writes through the same ingestion path, so it honours METRANA_INGESTION_URL and takes --ingestion-url as its explicit override.