---
title: "List a Brand's documents"
method: GET
path: "/context/brands/{slug}/documents"
tags: ["Documents"]
---

# List a Brand's documents

`GET /context/brands/{slug}/documents`

## Request

- Base URL: `https://api.adcrunch.dev`
- URL: `https://api.adcrunch.dev/context/brands/{slug}/documents`
- Auth: HTTP bearer

Lists the documents of a Brand, newest first. Each row has a URL to read the file from. A reservation with no bytes is not in the list, because it has no file.

One page at a time: `limit` rows at most, 100 by default. When the answer holds `nextCursor`, more rows exist: send it back as `cursor` to get the next page.

## Path parameters

- `slug` string, required

## Query parameters

- `cursor` string: 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, required: 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`.

## Response `200`

One page of the Brand’s finalized Documents, newest first. A reservation whose bytes never arrived is never listed, because there is no readable object behind it. This page is the last one, so it carries no `nextCursor`.

- object
  - `data` object[], required
    - `createdAt` number, required: Milliseconds since the Unix epoch, UTC.
    - `filename` string, required
    - `id` string, required
    - `mimeType` string, required
    - `name` string, required: The display name. Falls back to the filename.
    - `sizeBytes` number, required: Read off the stored object at finalize, never from the client.
    - `targetId` string, required
    - `targetType` string, required: What the Document is attached to. `brand` today.
    - `url` string, required
  - `nextCursor` string: Send this value as `cursor` to get the next page. It is absent on the last page.

## Other responses

- `400`: The request does not match the schema of this operation: a field is missing or has the wrong type, or the body is not valid JSON. `error` is `invalid_request`, and `issues` names each field. Nothing was changed. Or AdCrunch cannot use the `cursor`: it cannot read it, or the cursor belongs to a different query. Then `error` is `invalid_cursor`. Send the `nextCursor` of the previous page with no change, or omit `cursor` to get the first page.
- `401`: No API key, or one that does not resolve. See the security scheme. `error` is `unauthorized`.
- `402`: The organization has no active subscription. An owner subscribes at `paywallUrl`. `error` is `organization_unentitled`.
- `403`: The caller does not hold `brand:read`. `error` is `forbidden`.
- `404`: No Brand with that slug. `error` is `not_found`.

---

[API](https://skmtc.dev/adcrunch/apis/adcrunch-api.md) · [All operations](https://skmtc.dev/adcrunch/apis/adcrunch-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adcrunch/apis/adcrunch-api/revisions/a420ba80914f?raw)