Content Delivery API > Pagination

Pagination allows you to efficiently retrieve large sets of records by breaking them into manageable chunks. This helps optimize performance and reduce data transfer.

Limit results with first

Control the number of elements returned in a single query using the first parameter.

• Default limit: 20 records

• Maximum limit: 100 records

The following query returns the first 5 artist records:

{
  allArtists(first: 5) {
    id
    name
  }
}

Skip records with skip

Use the skip parameter to offset your results, allowing you to implement pagination across multiple requests:

{
  allArtists(first: 5, skip: 10) {
    id
    name
  }
}

This query skips the first 10 records and then returns the next 5.

Calculating total number of results

To determine the total number of records and implement client-side pagination, use the _XXXMeta query:

query {
  allArtists(filter: { name: { in: [ "Blank Banshee", "Gazelle Twin" ] }}) {
    id
    name
    genre
  }
  _allArtistsMeta(filter: { name: { in: [ "Blank Banshee", "Gazelle Twin" ] }}) {
    count
  }
}

Make sure to apply the same filters to both your regular query and the meta query; otherwise, the result count will be different!

Simplifying pagination

It is possible to automate the retrieval of a number of records that surpasses the 100-record limit without the need for manually handling the pagination logic by utilizing our GraphQL client @datocms/cda-client:

import { executeQueryWithAutoPagination } from "@datocms/cda-client";

const { allQuotes } = await executeQueryWithAutoPagination(`
  query {
    # notice that we're fetching 5,000 records here!
    allArtists(first: 5000) { name }
  }
`, { ... });

You can find all the details in the documentation for the executeQueryWithAutoPagination function.