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

# Pagination

> How list endpoints paginate and how to iterate through all pages.

List endpoints in Memic use page-based pagination with `page` and `page_size`
query parameters. The response includes enough metadata to know whether more
pages exist.

## Request

```bash theme={null}
curl "https://api.memic.ai/api/v1/files?page=1&page_size=50" \
  -H "X-API-Key: mk_live_..."
```

### Query parameters

| Parameter   | Type    | Default | Max   | Description           |
| ----------- | ------- | ------- | ----- | --------------------- |
| `page`      | integer | `1`     | —     | 1-indexed page number |
| `page_size` | integer | `50`    | `100` | Items per page        |

## Response shape

```json theme={null}
{
  "items": [
    { "id": "...", "name": "contract.pdf", ... },
    { "id": "...", "name": "handbook.md", ... }
  ],
  "total": 237,
  "page": 1,
  "page_size": 50,
  "has_more": true
}
```

* **`items`** — the array of results for the current page
* **`total`** — total count across all pages
* **`page`** — the page you requested (echoed back)
* **`page_size`** — the page size you requested (echoed back)
* **`has_more`** — `true` if another page exists

## Iterating through all pages

### Python (using the SDK)

```python theme={null}
from memic import Memic

client = Memic()

for file in client.files.iter_all():
    print(file.name)
```

The SDK handles pagination transparently via a generator. Use this when you
need to process every file without thinking about pages.

### Python (manual)

```python theme={null}
page = 1
while True:
    response = client.files.list(page=page, page_size=100)
    for file in response.items:
        print(file.name)
    if not response.has_more:
        break
    page += 1
```

### cURL (bash)

```bash theme={null}
page=1
while :; do
  resp=$(curl -s "$MEMIC_BASE_URL/files?page=$page&page_size=100" \
    -H "X-API-Key: $MEMIC_API_KEY")
  echo "$resp" | jq -r '.items[].name'
  if [[ $(echo "$resp" | jq '.has_more') != "true" ]]; then
    break
  fi
  page=$((page + 1))
done
```

## Best practices

* **Prefer `page_size=100`** (the maximum) to reduce the number of round-trips
* **Don't re-fetch old pages** if you're only looking for new items — keep a
  local cursor of the highest `created_at` you've seen and filter client-side
* **Use the SDK's iterator** when you need to process everything — it handles
  pagination correctly even if items shift between pages due to concurrent
  writes