> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://platform.bctrl.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# List files

> List safe metadata for durable Files visible to the caller.

List durable Files visible to the caller. This Tool is not Runtime-bound; use
the [Files](/sdk/files) resource client when you need relationship filters.

## List Files

```ts
const result = await bctrl.tools.call("files.list", {
  prefix: "reports/",
  limit: 50,
});

for (const file of result.files) {
  console.log(file.id, file.name, file.size);
}
console.log(result.nextCursor);
```

This Tool is synchronous. Use the [Files](/sdk/files) resource client when you
need upload, download, update, or delete operations.

## Request parameters

| Parameter | Type      | Required | Description                                        |
| --------- | --------- | -------- | -------------------------------------------------- |
| `prefix`  | `string`  | No       | Return paths beginning with this prefix.           |
| `cursor`  | `string`  | No       | Cursor returned by the previous page.              |
| `limit`   | `integer` | No       | Results per page. Defaults to `50`; maximum `200`. |

## Response

The result is `{ files, nextCursor }`:

| Field                 | Type                 | Always present | Description                                        |
| --------------------- | -------------------- | -------------- | -------------------------------------------------- |
| `files[].id`          | `FileId`             | Yes            | Durable File identifier.                           |
| `files[].name`        | `string`             | Yes            | File name.                                         |
| `files[].contentType` | `string \| null`     | Yes            | MIME type, when known.                             |
| `files[].size`        | `number`             | Yes            | Size in bytes.                                     |
| `files[].metadata`    | `JsonObject \| null` | Yes            | Public metadata, when stored.                      |
| `files[].createdAt`   | `string`             | Yes            | Creation timestamp.                                |
| `nextCursor`          | `string \| null`     | Yes            | Cursor for the next page, or `null` when complete. |

## Next

* [Files](/sdk/files) — manage durable File resources
* [Read text](/sdk/tools/files/files-read_text) — read bounded UTF-8 content
* [Runtime files](/sdk/tools/runtime/runtime-files-list) — inspect a live workspace