<!-- Markdown twin of https://pixelvault.dev/docs/pagination/ -->

# Pagination

List endpoints for media and collections use offset pagination with two query parameters, `page` and `per_page`, and return the page in `data` plus a `meta` object with the total.

```
curl "https://api.pixelvault.dev/v1/images?page=2&per_page=50" \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

```
{
  "data": [
    { "id": "img_abc123", "url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.png" }
  ],
  "meta": { "total": 132, "page": 2, "per_page": 50 }
}
```

## Parameters

Param

Default

Range

`page`

1

Integer, 1 or more

`per_page`

20

Integer, 1–100

Out-of-range values are clamped rather than rejected: `per_page=500` returns 100 items, `page=0` or a non-number falls back to the default. Send integers. Only invalid _filters_ return `400`.

## Response

`meta.total` counts every item matching your filters, so the last page is `ceil(total / per_page)`. There is no cursor, `has_more`, or `total_pages` field: stop when `page * per_page >= total`. Results are newest first (`created_at` descending), except a full-text image search (`q`), which is best match first. Because pages are offsets, items uploaded while you page can shift later pages by a few rows; dedupe on `id` if that matters.

Example

Node.jsPython

```
// Walk every image in the project, 100 at a time.
async function* allImages() {
  for (let page = 1; ; page++) {
    const res = await fetch(`https://api.pixelvault.dev/v1/images?page=${page}&per_page=100`, {
      headers: { Authorization: `Bearer ${process.env.PIXELVAULT_API_KEY}` },
    });
    if (!res.ok) throw new Error(`List failed: ${res.status}`);
    const { data, meta } = await res.json();
    yield* data;
    if (page * meta.per_page >= meta.total) return;
  }
}

for await (const image of allImages()) console.log(image.url);
```

## Paginated lists

Endpoint

Filters

[`GET /v1/images`](/docs/api/images/#list_images)

`collection_id`, `metadata`/`meta[key]`, `q` (AI description search), `tag`

[`GET /v1/videos`](/docs/api/videos/#list_videos)

`folder` (`400 invalid_folder` if malformed), `collection_id`, `metadata`/`meta[key]`

[`GET /v1/audio`](/docs/api/audio/#list_audio)

`folder`, `collection_id`, `metadata`/`meta[key]`

[`GET /v1/collections`](/docs/api/collections/#list_collections)

`type`, `name`

Filters combine with AND. Metadata filters are described in [Organize media](/docs/guides/organize-media/#metadata).

## Lists that return everything

Endpoint

Returns

[`GET /v1/images/tags`](/docs/api/images/#list_image_tags)

The 40 most used AI tags with counts

[`GET /v1/keys`](/docs/api/api-keys/#list_keys)

Every key in the project (at most 25)

[`GET /v1/webhooks`](/docs/api/webhooks/#list_webhooks)

`data.webhooks` plus the plan's endpoint `limit` and `remaining` (at most 10 endpoints)

[`GET /v1/webhooks/:id/deliveries`](/docs/api/webhooks/#list_webhook_deliveries)

The newest deliveries; `limit` 1–100, default 50, no offset

[`GET /v1/collections/:id`](/docs/api/collections/#get_collection)

The collection with all of its members

## Next steps

-   [Export all media](/docs/guides/export-media/) instead of paging through everything to back it up.
-   [Search images](/docs/guides/ai-descriptions/) by their AI descriptions.
