# Pagination & Large Datasets

The Cineamo API uses cursor-based pagination for endpoints that return large datasets.

## 🔄 How Pagination Works

When a response contains many items, the API returns them in pages. Each response includes:

- A list of items for the current page
- Metadata about pagination
- Links to navigate between pages

## Pagination Parameters

### Request Parameters

- `limit` - Number of items per page (default: 25, max: 100)
- `cursor` - Cursor token for the next/previous page

### Example Request

```bash
curl -X GET "https://api.cineamo.com/api/v1/movies?limit=50&cursor=abc123" \
  -H "Authorization: Bearer your_access_token"
```

## Pagination Response Format

```json
{
  "data": [
    {
      "id": "movie_123",
      "title": "Example Movie"
    }
    // ... more items
  ],
  "pagination": {
    "total": 250,
    "limit": 50,
    "has_more": true,
    "next_cursor": "xyz789",
    "prev_cursor": "def456"
  }
}
```

### Response Fields

- `data` - Array of items for the current page
- `pagination.total` - Total number of items across all pages
- `pagination.limit` - Number of items per page
- `pagination.has_more` - Whether more pages are available
- `pagination.next_cursor` - Cursor for the next page
- `pagination.prev_cursor` - Cursor for the previous page

## Iterating Through Pages

### Example: Fetch All Pages

```javascript
async function fetchAllMovies() {
  const allMovies = [];
  let cursor = null;

  do {
    const url = cursor
      ? `https://api.cineamo.com/api/v1/movies?cursor=${cursor}`
      : 'https://api.cineamo.com/api/v1/movies';

    const response = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    });

    const json = await response.json();
    allMovies.push(...json.data);

    cursor = json.pagination.has_more ? json.pagination.next_cursor : null;
  } while (cursor);

  return allMovies;
}
```

## Best Practices

- **Use appropriate page sizes** - Larger pages reduce requests but increase response time
- **Implement rate limiting** - Don't fetch too many pages too quickly
- **Cache results** when appropriate
- **Handle pagination errors** gracefully
- **Use cursors** instead of offset-based pagination for consistency