Valgo API

The official Python client for the Valgo API to upload, share, and retrieve datasets programmatically.

Installation

pip install valgo

Valgo supports Python 3.11 and newer.

Quick start

Set the API key issued by your Valgo administrator:

export VALGO_API_KEY="valgo_live_..."

Upload a file:

from valgo import Valgo

client = Valgo()
uploaded = client.upload("data/dataset.parquet")
print(uploaded.artifact_id)

The SDK connects to https://api.valgo.ai by default.

You can also pass the key directly:

client = Valgo(api_key="valgo_live_...")

Uploads

Upload a local file with an optional logical name and metadata. The first argument is the file's path on your computer. name is how the file is identified in shared storage for listing and later access; it does not need to match the local path.

uploaded = client.upload(
    "data/dataset.parquet",          # Local file
    name="datasets/dataset.parquet", # Name in shared storage
    metadata={"source": "example"},
    progress=True,
)

Directories are uploaded concurrently:

result = client.upload("data/datasets")

for uploaded in result.completed:
    print(uploaded.path, uploaded.artifact_id)

for failure in result.failures:
    print(failure.path, failure.error)

Interrupted uploads are resumable. Retrying the same file continues the existing transfer rather than creating a duplicate.

Downloads

Download the latest version by logical name:

client.download("datasets/dataset.parquet", "downloads/dataset.parquet", progress=True)

Or retrieve an exact immutable version:

client.download(uploaded.artifact_id, "downloads/dataset.parquet")

The SDK verifies the downloaded size and SHA-256 checksum before replacing the destination file.

Listing

List the latest visible version of each artifact for the API key's integration:

page = client.list()

for artifact in page.items:
    print(artifact.name, artifact.version, artifact.size_bytes)

Or print a formatted table directly while retaining the page result:

page = client.list(pretty=True)

Filter by logical path prefix or include version history:

page = client.list(prefix="reports/", all_versions=True, limit=100)
next_page = client.list(prefix="reports/", all_versions=True, limit=100, cursor=page.next_cursor)

Listing requires data:read. Deleted, pending-purge, incomplete, and other integrations' artifacts are never returned.

Deletion

Delete one exact artifact version using the ID returned by an upload:

result = client.delete(uploaded.artifact_id)
print(result.status)

Deleting by logical name requires explicit confirmation that every version should be removed:

client.delete("datasets/dataset.parquet", all_versions=True)

The API key must include the data:delete scope. Files uploaded through Valgo are removed from object storage. Customer-owned objects added with attach() are detached from Valgo by default; pass delete_source=True only when the source S3 object should also be removed. S3 versioning or Object Lock may retain historical versions according to the customer's AWS policy.

Configuration

Constructor arguments override environment variables:

client = Valgo(
    api_key="valgo_live_...",
    base_url="https://api.valgo.ai",
    timeout=60,
    max_workers=8,
)

Development

From this repository:

python -m pip install -e .
pytest

Do not commit API keys, presigned URLs, or customer data. Report security issues privately to the Valgo team rather than opening a public issue.

License

Licensed under the Apache License 2.0.

Copyright © 2026 Valgorithmic, Inc. (d.b.a. Valgo).