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. Get it from the user menu → Get API token in the portal.

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 the API rejects, or one whose owner cannot reach 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`

base_url also falls back to artifact_api_url from metrana.init() before the environment variable — see Service endpoints.

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.

Constructor

Argument	Default	Purpose
`api_key`	`None`	Falls back to `METRANA_API_KEY`.
`base_url`	`None`	Falls back to `METRANA_ARTIFACT_API_URL`, then the default endpoint.
`connect_timeout`	`10.0`	Connection establishment, in seconds.
`read_timeout`	`60.0`	Per-request read timeout, in seconds.
`max_retries`	`5`	Retry budget for transient failures.
`pool_maxsize`	`16`	Size of the connection pool.

All are keyword-only. The base_url in use is readable back as the base_url property.

Methods

Method	Purpose
`create_artifact(...)`	Start a draft version.
`declare_manifest(...)`	Declare the file manifest, getting back upload instructions.
`presign_parts(version_id, digest, *, upload_id, from_part, count)`	Fetch a window of presigned multipart URLs.
`complete_multipart(...)`	Finish a multipart upload.
`commit(version_id)`	Commit the draft, making the version real.
`set_alias(...)` / `delete_alias(...)`	Move or remove an alias.
`resolve_version(...)` / `resolve_alias(...)`	Resolve a version index or alias to a `VersionInfo`.
`list_files(...)` / `iter_files(version_id)`	List a version’s files, paged or as an iterator.
`list_download(...)` / `iter_download(version_id)`	Same, but with presigned download URLs attached.
`close()`	Release the connection pool.

Prefer the iter_* forms over the list_* forms for anything that could be large — they page for you instead of materializing every entry at once.