---
title: head
description: Fetch an object's metadata without materializing its body - one key or many. Body accessors lazy-fetch on call.
---

`files.head(key)` · `files.head(keys)`

Returns the same [`StoredFile`](/api/stored-file) shape as [`download`](/api/download), without materializing the body. Calling a body accessor on the result lazy-fetches.

```ts lineNumbers
const info = await files.head("avatars/abc.png");
// → StoredFile with no body materialized
```

## Many keys

Pass an array to fetch metadata for many in one call. Returns `{ files, errors? }` instead of throwing on partial failure (a missing key lands in `errors`), honoring `concurrency` / `stopOnError`.

```ts lineNumbers
const result = await files.head(["avatars/a.png", "avatars/b.png"]);

result.files; // StoredFile[] — successes, in the order supplied
result.errors; // undefined when every key succeeded
```