Reading

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 signedReadUrl for a link that reads a private object without going through your server.

import { bucket } from "@/lib/blob"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

The records these return (BlobObject, BlobInfo, BlobDownload) are on Types.

get#

const res = await bucket.get("reports/2026-01.pdf")res.contentType  // 'application/pdf'res.size         // 184_302res.etag         // '"9f3c..."'res.metadata     // { owner: 'u7' }res.body         // ReadableStream<Uint8Array>

body is a stream and nothing is buffered for you. Wrap it in a Response for the usual conversions:

const text = await new Response((await bucket.get("notes/1.md")).body).text()const buffer = await new Response((await bucket.get("img/1.png")).body).arrayBuffer()

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.uploadedAt   // Date

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")) {  // ...}

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#

const page = await bucket.list({ prefix: "avatars/", limit: 100 })page.blobs  // BlobObject[]page.cursor // string | undefined, set only while more remains

All three are optional.

A full walk is a do ... while:

let cursor: string | undefinedconst paths: string[] = []do {  const page = await bucket.list({ prefix: "avatars/", limit: 1000, cursor })  for (const blob of page.blobs) paths.push(blob.path)  cursor = page.cursor} while (cursor)

Each entry is a BlobObject: path, size, etag, timestamp and URLs. There is no contentType or metadata; reading those is one info() per object.

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'

Every record on a public bucket already carries url; publicUrl gives you one for any path. It returns undefined on a private bucket and throws a TypeError for an empty path or one with a . or .. segment.

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.

versionedUrl#

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

versionedUrl is ${url}?v=${etag}, 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, url never changes and caches keep serving the old bytes.

Pair it with cache: 'immutable' at upload. See Caching.

Private buckets#

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

A private bucket has no public host, so url and versionedUrl are undefined on every record. 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 signedReadUrl().

signedReadUrl#

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

A time-limited URL anyone can GET. Use it on a private bucket, or for an object you do not want linked from a public page.

All three are optional.

Use expiresAt, not expiresIn#

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)}

expiresIn is what you asked for. expiresAt is what you got, and it can be sooner, because a link cannot outlive the credential that signed it. Cache the link until expiresAt, never until a deadline you compute yourself. This applies to signedUploadUrl too. The reason is on How signing works.

downloadAs#

await bucket.signedReadUrl(path, { 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.

contentType#

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

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

Next steps#