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 streamconst info = await bucket.info("reports/2026-01.pdf")  // record onlyconst ok = await bucket.exists("reports/2026-01.pdf")  // booleanconst page = await bucket.list({ prefix: "reports/" }) // one page of records

res = bucket.get("reports/2026-01.pdf")     # record plus the bytesinfo = bucket.info("reports/2026-01.pdf")   # record onlyok = bucket.exists("reports/2026-01.pdf")   # boolpage = bucket.list(prefix="reports/")       # one page of records

// record plus body stream; close itres, err := bucket.Get(ctx, "reports/2026-01.pdf")// record onlyinfo, err := bucket.Info(ctx, "reports/2026-01.pdf")// boolok, err := bucket.Exists(ctx, "reports/2026-01.pdf")// one page of recordspage, 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_302info.etag         // '"9f3c..."'info.contentType  // 'application/pdf'info.metadata     // { owner: 'u7' }

info = bucket.info("reports/2026-01.pdf")info.size          # 184302info.etag          # '"9f3c..."'info.content_type  # 'application/pdf'info.metadata      # {'owner': 'u7'}

info, err := bucket.Info(ctx, "reports/2026-01.pdf")info.Size        // 184302info.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 | undefineddo {  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 = Nonewhile 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 consoleblob.url          // undefinedblob.versionedUrl // undefinedawait bucket.publicUrl("reports/2026-01.pdf")  // undefined

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

// a bucket set to private in the consoleb, 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 linklink.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, timezonelink = 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.