Copy page

Guides

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

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

Pagination Response Format

Code
{
  "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

Code
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