Reading - Upstash Documentation

This page covers reading objects from your server: get for the bytes, info for the facts, exists for a boolean, list for a page of keys, and signed read URLs for a link that reads a private object without going through your server.

const res = await bucket.get("reports/2026-01.pdf")    // record plus body stream
const info = await bucket.info("reports/2026-01.pdf")  // record only
const ok = await bucket.exists("reports/2026-01.pdf")  // boolean
const page = await bucket.list({ prefix: "reports/" }) // one page of records

res = bucket.get("reports/2026-01.pdf")     # record plus the bytes
info = bucket.info("reports/2026-01.pdf")   # record only
ok = bucket.exists("reports/2026-01.pdf")   # bool
page = bucket.list(prefix="reports/")       # one page of records

// record plus body stream; close it
res, err := bucket.Get(ctx, "reports/2026-01.pdf")
// record only
info, err := bucket.Info(ctx, "reports/2026-01.pdf")
// bool
ok, err := bucket.Exists(ctx, "reports/2026-01.pdf")
// one page of records
page, err := bucket.List(ctx, &blob.ListOptions{Prefix: "reports/"})

The records these return are on Types. Method signatures and option types: TypeScript, Python, Go.

get

const res = await bucket.get("reports/2026-01.pdf")

res.contentType  // 'application/pdf'
res.metadata     // { owner: 'u7' }
res.body         // ReadableStream<Uint8Array>

res = bucket.get("reports/2026-01.pdf")

res.content_type  # 'application/pdf'
res.metadata      # {'owner': 'u7'}
res.content       # bytes, read in full; bucket.stream() leaves them on the wire

res, err := bucket.Get(ctx, "reports/2026-01.pdf")
if err != nil {
	return err
}
defer res.Body.Close()

res.ContentType // "application/pdf"
res.Metadata    // map[owner:u7]
res.Body        // io.ReadCloser

get returns the object’s record, with its content type and metadata, plus the body. In TypeScript and Go the body is a stream and nothing is buffered for you; Python’s get reads it in full, and stream() does not. Reading the body in each SDK: TypeScript, Python, Go. A missing object throws a BlobError with code not_found, status 404. See Errors. There is no range option. For byte ranges, use an S3 client.

info

const info = await bucket.info("reports/2026-01.pdf")

info.size         // 184_302
info.etag         // '"9f3c..."'
info.contentType  // 'application/pdf'
info.metadata     // { owner: 'u7' }

info = bucket.info("reports/2026-01.pdf")

info.size          # 184302
info.etag          # '"9f3c..."'
info.content_type  # 'application/pdf'
info.metadata      # {'owner': 'u7'}

info, err := bucket.Info(ctx, "reports/2026-01.pdf")

info.Size        // 184302
info.ETag        // "\"9f3c...\""
info.ContentType // "application/pdf"
info.Metadata    // map[owner:u7]

One HEAD request. The same record as get without the bytes, so reading a 2 GB object’s facts is cheap. A missing object throws not_found. Metadata comes back from get and info only, with keys lowercased. See Metadata.

exists

if (await bucket.exists("avatars/u7.png")) {
  // ...
}

if bucket.exists("avatars/u7.png"):
    ...

ok, err := bucket.Exists(ctx, "avatars/u7.png")
if err != nil {
	return err
}
if ok {
	// ...
}

The same HEAD request as info, answering false instead of throwing. If you need the etag, size or metadata anyway, call info and catch not_found instead of making two round trips.

list

let cursor: string | undefined

do {
  const page = await bucket.list({ prefix: "avatars/", limit: 1000, cursor })
  for (const blob of page.blobs) console.log(blob.path)
  cursor = page.cursor
} while (cursor)

cursor = None

while True:
    page = bucket.list(prefix="avatars/", limit=1000, cursor=cursor)
    for blob in page.blobs:
        print(blob.path)
    cursor = page.cursor
    if not cursor:
        break

cursor := ""

for {
	page, err := bucket.List(ctx, &blob.ListOptions{
		Prefix: "avatars/",
		Limit:  1000,
		Cursor: cursor,
	})
	if err != nil {
		return err
	}
	for _, b := range page.Blobs {
		fmt.Println(b.Path)
	}
	if page.Cursor == "" {
		break
	}
	cursor = page.Cursor
}

list returns one page of records and a cursor. The cursor is set only while more remains; pass it back for the next page. A full walk loops until it is unset. All three options are optional.

Option	Default	Description
Prefix	none, the whole bucket	Only keys starting with this.
Limit	storage picks, at most 1000	Page size, clamped to 1 to 1000.
Cursor	none, the first page	The cursor from the previous page.

Each entry carries path, size, etag, timestamp and URLs. There is no content type or metadata; reading those is one info per object. The prefix is the only filter. There is no query by owner, type or date, so “this user’s files” has to be a prefix you chose at upload time. An app that needs to query its files should keep its own table and treat the bucket as storage, not an index.

Public URLs

await bucket.publicUrl("avatars/u7.png")
// 'https://b0f3a91c24d.blob.upstash.io/avatars/u7.png'

bucket.public_url("avatars/u7.png")
# 'https://b0f3a91c24d.blob.upstash.io/avatars/u7.png'

bucket.PublicURL(ctx, "avatars/u7.png")
// "https://b0f3a91c24d.blob.upstash.io/avatars/u7.png"

Every record on a public bucket already carries its URL; the public URL call gives you one for any path. It returns nothing on a private bucket. An empty path, or one with a . or .. segment, is rejected before any request is sent; see Paths. The URL itself is built from the token, but whether the bucket has a public host at all is known only to the backend, so the first call on a fresh client fetches credentials. They are cached, so every call after that is local.

Versioned URLs

const avatar = await bucket.info(`avatars/${user.id}.png`)
avatar.versionedUrl // https://.../avatars/u7.png?v=%229f3c...%22

avatar = bucket.info(f"avatars/{user.id}.png")
avatar.versioned_url  # https://.../avatars/u7.png?v=%229f3c...%22

avatar, err := bucket.Info(ctx, "avatars/"+user.ID+".png")
avatar.VersionedURL // https://.../avatars/u7.png?v=%229f3c...%22

<img src={avatar.versionedUrl} />

The versioned URL is the URL with ?v=<etag> appended, so it changes whenever the content does. Use it for a stable path that gets overwritten: if avatars/u7.png is replaced every time the user picks a new picture, the plain URL never changes and caches keep serving the old bytes. Pair it with cache: 'immutable' at upload. See Caching.

Private buckets

const blob = await bucket.put("reports/2026-01.pdf", pdf) // a bucket set to private in the console
blob.url          // undefined
blob.versionedUrl // undefined
await bucket.publicUrl("reports/2026-01.pdf")  // undefined

blob = bucket.put("reports/2026-01.pdf", pdf)  # a bucket set to private in the console
blob.url            # None
blob.versioned_url  # None
bucket.public_url("reports/2026-01.pdf")  # None

// a bucket set to private in the console
b, err := bucket.Put(ctx, "reports/2026-01.pdf", pdf, nil)
b.URL          // ""
b.VersionedURL // ""

bucket.PublicURL(ctx, "reports/2026-01.pdf") // ""

A private bucket has no public host, so no record carries a URL or versioned URL. Nothing in the code declares this: the SDK learns it from the backend when it fetches credentials, and objects are stored with Cache-Control: private. Reads go through signed read URLs.

Signed read URLs

const { url, expiresAt } = await bucket.signedReadUrl("reports/2026-01.pdf", {
  expiresIn: "2m",
  downloadAs: "Report Q3.pdf",
})

link = bucket.signed_read_url("reports/2026-01.pdf", expires_in="2m", download_as="Report Q3.pdf")
link.url, link.expires_at

link, err := bucket.SignedReadURL(ctx, "reports/2026-01.pdf",
	&blob.SignedReadURLOptions{
		ExpiresIn:  2 * time.Minute,
		DownloadAs: "Report Q3.pdf",
	})
link.URL       // the link
link.ExpiresAt // when it stops working

A time-limited URL anyone can GET, returned with the moment it expires. Use it on a private bucket, or for an object you do not want linked from a public page. Names and types: TypeScript, Python, Go. All three options are optional.

Option	Default	Description
Expires in	`'5m'`	How long to ask for, at most `'10m'`. `'2m'`, `'10m'`, or a bare number of seconds. A longer ask gets 10 minutes.
Download as	none, displayed inline	Save as this filename instead of displaying inline.
Content type	the stored type	What storage answers with as `Content-Type`, overriding what was stored.

Use the returned expiry

const cached = await cache.get(key)
if (!cached || cached.expiresAt < new Date()) {
  const link = await bucket.signedReadUrl(path, { expiresIn: "5m" })
  await cache.set(key, link)
}

from datetime import datetime, timezone

link = cache.get(key)
if link is None or link.expires_at < datetime.now(timezone.utc):
    link = bucket.signed_read_url(path, expires_in="5m")
    cache.set(key, link)

link, ok := cache.Get(key)
if !ok || link.ExpiresAt.Before(time.Now()) {
	opts := &blob.SignedReadURLOptions{ExpiresIn: 5 * time.Minute}
	fresh, err := bucket.SignedReadURL(ctx, path, opts)
	if err != nil {
		return err
	}
	link = fresh
	cache.Set(key, link)
}

What you pass as expires-in is what you asked for. The expiry that comes back is what you got, and it can be sooner, because no link lives longer than 10 minutes. Cache the link until the returned expiry, never until a deadline you compute yourself. This applies to signed upload URLs too. The reason is on How signing works.

Download filename

await bucket.signedReadUrl(path, { downloadAs: "café ☕.pdf" })

bucket.signed_read_url(path, download_as="café ☕.pdf")

bucket.SignedReadURL(ctx, path, &blob.SignedReadURLOptions{
	DownloadAs: "café ☕.pdf",
})

Sets Content-Disposition: attachment, so the browser saves the file under that name rather than rendering it. Unicode names arrive intact. The filename is signed into the URL, so it cannot be edited afterwards.

Content type override

await bucket.signedReadUrl("exports/rows.bin", { contentType: "text/csv" })

bucket.signed_read_url("exports/rows.bin", content_type="text/csv")

bucket.SignedReadURL(ctx, "exports/rows.bin", &blob.SignedReadURLOptions{
	ContentType: "text/csv",
})

Overrides what storage answers with, without rewriting the object. Refused with invalid_input if it is not a valid media type.

Next steps

Writing

put, metadata, conditional writes and multipart from the server.

Caching

What Cache-Control an object is stored with, and pairing it with a versioned URL.

Deleting

One path, a list, a prefix, and sweeping incomplete uploads.

Errors

The error codes, what reaches the browser, and platform body limits.

​get

​info

​exists

​list

​Public URLs

​Versioned URLs

​Private buckets

​Signed read URLs

​Use the returned expiry

​Download filename

​Content type override

​Next steps