---
title: document_list
description: List the files of a brand, each with its URL.
---

Ask which files a brand has. The agent lists them, each with a link.

> "Which brand files do we have for Acme?"

The agent calls `document_list` for Acme. You see each file with its name, its type, its size and its link.

The job guide [Describe a brand](/mcp/tools/describe-a-brand) shows each step of the job.

## Reference

List the files attached to a brand — logos, guidelines, decks — newest first, each with a URL you can fetch. Uploads that never completed are not listed, so every URL here resolves. The answer holds at most `limit` rows (default 100, maximum 500). When it carries `nextCursor`, more rows exist: call this tool again with the same arguments and `cursor` set to that value. When it carries no `nextCursor`, you have every row.

### Input

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `brand_name` | string | yes | The brand slug whose files to list. |
| `cursor` | string, at least 1 character | no | The `nextCursor` of the previous page. Omit it to get the first page. Send it with no change, and with the same filters as the request that answered it: a cursor from a different query gets a 400 `invalid_cursor`. Do not build or change a cursor. |
| `limit` | integer, 1 to 500 | no | The greatest number of rows on the page, from 1 to 500. The default is 100. A greater value gets a 400, with `error` of `invalid_request`. Default: `100`. |

### Output

A successful call returns this object in `structuredContent`.

| Field | Type | Always present | Description |
| --- | --- | --- | --- |
| `documents` | array of object | yes | The finalized documents of the brand, newest first. An upload that nobody finalized is not in the list. |
| `documents[].createdAt` | number | yes | Milliseconds since the Unix epoch, in UTC. |
| `documents[].filename` | string | yes | The name of the file at upload. |
| `documents[].id` | string | yes | The id of the document (`doc_…`). |
| `documents[].mimeType` | string | yes | The media type of the stored file. AdCrunch reads it from the file at finalize. |
| `documents[].name` | string | yes | The display name. It is the filename until someone renames it. |
| `documents[].sizeBytes` | number | yes | The size of the stored file, in bytes. AdCrunch reads it from the file at finalize. |
| `documents[].targetId` | string | yes | The id of the brand that holds the document (`brd_…`). |
| `documents[].targetType` | string | yes | The kind of record that holds the document: `brand`. |
| `documents[].url` | string | yes | The public URL of the file. Each person who has the URL can read the file. |
| `nextCursor` | string | no | Send this value as `cursor` to get the next page. It is absent on the last page. |

### Failure codes

A failed call has `isError` set, and `structuredContent.error` holds one of these codes. [Errors](/mcp/errors) describes the shape of a failed call.

- `not_found`
- `invalid_cursor`
- `forbidden`
- `invalid_request`
- `internal_error`

### Scope

The token must hold `brand:read`. [Auth & scopes](/mcp/auth) lists each scope.

### Annotations

A client reads these hints. A hint that the tool does not declare has the default value of the MCP specification.

- **Read-only.** The tool changes nothing.
- **Closed world.** The tool reads and writes the data of AdCrunch only.

### Example

The arguments:

```json
{
  "brand_name": "acme"
}
```

The result, in `structuredContent`:

```json
{
  "documents": [
    {
      "createdAt": 1790086400000,
      "filename": "acme-logo.png",
      "id": "doc_7d1f58",
      "mimeType": "image/png",
      "name": "acme-logo.png",
      "sizeBytes": 48213,
      "targetId": "brd_6a9c33",
      "targetType": "brand",
      "url": "https://documents.adcrunch.dev/org_3a7f10/doc_7d1f58"
    },
    {
      "createdAt": 1790000000000,
      "filename": "acme-brand-guidelines.pdf",
      "id": "doc_5e2b41",
      "mimeType": "application/pdf",
      "name": "acme-brand-guidelines.pdf",
      "sizeBytes": 1482064,
      "targetId": "brd_6a9c33",
      "targetType": "brand",
      "url": "https://documents.adcrunch.dev/org_3a7f10/doc_5e2b41"
    }
  ]
}
```