List and Download Files

Use alloy.storage read helpers when you need to inspect upload object names or download uploaded files from Python.

from alloy import storage

with storage.connect() as store:
    listing = store.list_files(path="flights/run-001")

Prefixes and keys

Upload helpers accept friendly SDK path values:

flights/run-001

For SDK uploads, list helpers accept the same path value. For any Mesh-visible folder, pass a raw prefix instead:

uploads/sdk-uploads/flights/run-001
uploads/sdk-uploads/flights/run-001/run.mcap

Downloads use exact Mesh key strings, usually from an upload or list result.

In v1, SDK read helpers accept uploads/... prefixes and keys only. That includes web uploads and SDK uploads, but not devices/<device-id>/... paths yet.

List files

from alloy import storage

with storage.connect() as store:
    listing = store.list_files(
        path="flights/run-001",
        recursive=False,
        max_keys=100,
    )

for directory in listing.directories:
    print("dir", directory)

for file in listing.files:
    print(file.key, file.size, file.last_modified)

recursive=False uses folder-like delimiters. Set recursive=True to return files below nested folders.

Pagination

If a list response has more objects, next_token is set.

from alloy import storage

prefix = "uploads/sdk-uploads/flights/run-001"
token = None

with storage.connect() as store:
    while True:
        page = store.list_files(prefix=prefix, recursive=True, continuation_token=token)

        for file in page:
            print(file.key)

        token = page.next_token
        if token is None:
            break

Download one file

from alloy import storage

with storage.connect() as store:
    store.download_file(
        "uploads/sdk-uploads/flights/run-001/run.mcap",
        "local-copy.mcap",
    )

download_file downloads the exact key to the destination path.

One-shot helpers

from alloy import storage

listing = storage.list_files(path="flights/run-001", recursive=True)
storage.download_file("uploads/sdk-uploads/flights/run-001/run.mcap", "run.mcap")

Async one-shots:

from alloy import storage

listing = await storage.async_list_files(
    path="flights/run-001",
    recursive=True,
)
await storage.async_download_file(
    "uploads/sdk-uploads/flights/run-001/run.mcap",
    "run.mcap",
)

The SDK does not expose delete, move, rename, or overwrite operations in v1. Use Mesh Storage deletion workflows when you need to remove or replace files.