> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedrock.cv/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> How cursor-based pagination works in the Bedrock API.

All list endpoints return paginated results using **cursor-based pagination**. This approach provides stable, consistent paging even when new records are created between requests.

## Query Parameters

| Parameter | Type    | Default | Description                            |
| --------- | ------- | ------- | -------------------------------------- |
| `limit`   | integer | `20`    | Number of items per page (1--100)      |
| `cursor`  | string  | —       | Opaque cursor from a previous response |

## Response Shape

Every list endpoint returns a `data` array and a `_meta` object:

```json theme={null}
{
  "data": [
    { "id": "prj_01JABCD123", "name": "City Tower Phase 2", ... },
    { "id": "prj_01JABCD456", "name": "Harbor Bridge Retrofit", ... }
  ],
  "_meta": {
    "next": "eyJpZCI6InByal8wMUpBQkNENDU2IiwiY3JlYXRlZF9hdCI6IjIwMjQtMDYtMTVUMTA6MzA6MDBaIn0",
    "prev": "eyJpZCI6InByal8wMUpBQkNEMTIzIiwiY3JlYXRlZF9hdCI6IjIwMjQtMDYtMTZUMDg6MDA6MDBaIn0",
    "limit": 20
  }
}
```

| Field         | Description                                                              |
| ------------- | ------------------------------------------------------------------------ |
| `_meta.next`  | Cursor pointing to the next page. `null` when there are no more results. |
| `_meta.prev`  | Cursor pointing to the previous page. `null` on the first page.          |
| `_meta.limit` | The limit that was applied to this request.                              |

## Paging Forward

Pass the `next` cursor from the previous response to fetch the next page:

```bash theme={null}
# First page
curl "https://api.bedrock.cv/projects?limit=20" \
  -H "Authorization: Bearer sk_xxx"

# Next page
curl "https://api.bedrock.cv/projects?limit=20&cursor=eyJpZCI6InBya..." \
  -H "Authorization: Bearer sk_xxx"
```

Continue until `_meta.next` is `null`.

## Paging Backward

Pass the `prev` cursor to go back one page. This is useful for building "Previous / Next" navigation in a UI.

```bash theme={null}
curl "https://api.bedrock.cv/projects?limit=20&cursor=eyJpZCI6InBya..." \
  -H "Authorization: Bearer sk_xxx"
```

## Sort Order

Results are sorted by **creation date descending** (newest first), with `id` as a tiebreaker. This order is fixed and cannot be changed via query parameters.

## Cursor Format

Cursors are **opaque strings** — do not parse, construct, or store them long-term. They encode an internal position and may change format between API versions. Always use the cursor values returned in `_meta`.

## Example: Fetching All Projects

```bash theme={null}
#!/bin/bash
CURSOR=""
PAGE=1

while true; do
  URL="https://api.bedrock.cv/projects?limit=100"
  if [ -n "$CURSOR" ]; then
    URL="${URL}&cursor=${CURSOR}"
  fi

  RESPONSE=$(curl -s "$URL" -H "Authorization: Bearer sk_xxx")
  echo "Page $PAGE: $(echo "$RESPONSE" | jq '.data | length') items"

  CURSOR=$(echo "$RESPONSE" | jq -r '._meta.next // empty')
  if [ -z "$CURSOR" ]; then
    break
  fi
  PAGE=$((PAGE + 1))
done
```

## Notes

* The maximum `limit` is **100**. Requests above this value are clamped to 100.
* The minimum `limit` is **1**.
* An invalid or expired cursor returns a `400 Bad Request` error.
* File listing (`GET /files`) uses GCS continuation tokens instead of database cursors, but the response shape and query parameters are identical.