Configuration

Every artifact function takes the same handful of connection options. All are optional and fall back to environment variables or sensible defaults.

API key

The key authenticates you and must carry the artifacts:read and artifacts:write scopes (read for download/inspect, write for upload/alias). Create one in Settings → API keys.

Provide it via the api_key argument or — preferred — the METRANA_API_KEY environment variable:

export METRANA_API_KEY="your-api-key"

If no key is given and METRANA_API_KEY is unset, calls raise NoMetranaApiKeyError. A key that is missing the right scope, or isn’t bound to the workspace, raises MetranaArtifactAuthError.

Endpoint

Artifact calls target the artifact API, defaulting to https://artifacts.metrana.ai. Override it with the base_url argument or the METRANA_ARTIFACT_API_URL environment variable — mostly useful for self-hosted or staging deployments:

export METRANA_ARTIFACT_API_URL="https://artifacts.staging.example.com"

Workspace

Artifacts are scoped to a workspace. Every function takes workspace=…, but if you omit it the SDK uses the workspace from your active metrana.init(...) run — so inside a logged run you never repeat it:

metrana.init(workspace_name="my-team", project_name="proj", run_name="run-001")
metrana.upload_artifact("ckpt/", type="model", name="llm")   # workspace = "my-team"

With no workspace argument and no active run, calls raise MetranaArtifactValidationError.

Concurrency

upload_artifact and download_artifact take concurrency — the maximum number of simultaneous byte transfers (default 16). Transfers parallelise across files, and a single large file parallelises across its multipart parts. Raise it on a fast link; lower it to be gentle on a shared one.

Bring your own bucket

upload_artifact and download_artifact take an optional storage="s3://<bucket>/<prefix>". When set, artifact bytes are read/written directly to a bucket you own and Metrana stores only metadata — see Uploading → bring your own bucket.

This path needs the s3 extra (pip install 'metrana[s3]', see Installation) and your own AWS credentials, which are resolved from the standard boto3 chain — AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (and AWS_SESSION_TOKEN) environment variables, ~/.aws/config / ~/.aws/credentials, or an instance/pod role. Your credentials never leave your machine; Metrana neither receives nor stores them. There is no Metrana environment variable for storage — pass it per call.

Environment variables

Variable	Argument	Default
METRANA_API_KEY	api_key	(required)
METRANA_ARTIFACT_API_URL	base_url	https://artifacts.metrana.ai

An explicit argument always takes precedence over the environment variable. The storage= option (bring your own bucket) has no Metrana environment variable, but honours the standard AWS credential environment variables described above.

The low-level ArtifactClient

The six module-level functions cover almost every use. For fine-grained control there is also metrana.ArtifactClient — a synchronous, one-method-per-endpoint client for the artifact API control plane (create draft, declare manifest, presign parts, complete, commit, alias, resolve, list). It maps every non-2xx response to the MetranaArtifact* hierarchy, retries transient failures, and reuses connections. Use it as a context manager:

from metrana import ArtifactClient

with ArtifactClient() as client:            # api_key / base_url resolve as above
    version = client.resolve_alias(
        type="model", name="llm", alias="latest", workspace="my-team",
    )
    for entry in client.iter_files(version.version_id):
        print(entry.path, entry.size)

Reach for it only when you need to drive the upload/download protocol yourself; otherwise prefer upload_artifact / download_artifact, which orchestrate hashing, dedup, parallel transfer, and commit for you.