Catalog My learning Blog
API Design Course: REST and GraphQL Best Practices · Phase 3 · Lesson 17 · 3 min read

GraphQL Cursor Pagination: The Connections Spec

On this page
  1. Why GraphQL lists need connections
  2. The Relay connection spec: edges, nodes and pageInfo
  3. Implementing cursor pagination in a resolver
  4. Practical notes on GraphQL pagination
  5. Check yourself

Why GraphQL lists need connections

A field like posts: [Post!]! returns everything, with no way to page and no place to add metadata. Changing it later breaks clients. The connection pattern, from Facebook's Relay client and now a de-facto standard, gives every paginated list the same structure.

The Relay connection spec: edges, nodes and pageInfo

GraphQL
type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
}

type PostEdge {
  node: Post!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  endCursor: String
}

type Query {
  posts(first: Int = 10, after: String): PostConnection!
}

The nesting looks heavy at first. Read it as: a connection is a page; each edge is one slot on that page, holding the item (the node) plus a bookmark (the cursor) for that exact spot; pageInfo says whether there's another page and where to start it.

  • edges: each item (node) with its own cursor.
  • pageInfo: whether there are more items, and the cursor to continue from.
  • Arguments: first and after page forward; the full spec also defines last and before for paging backwards.
  • Edges can carry relationship data, like role on a team-membership edge or addedAt on a playlist edge, which belongs to the relationship, not to either object.
A connection returns edges, each holding a node and its cursor, plus pageInfo; the next request passes endCursor as the after argument.
A connection returns edges, each holding a node and its cursor, plus pageInfo; the next request passes endCursor as the after argument.

Implementing cursor pagination in a resolver

The resolver sorts newest first with the ID as a tiebreaker, and the cursor encodes the last item's sort values (the same keyset approach as REST, Day 7):

JavaScript
posts: (_, { first, after }) => {
  if (first > 50) throw new GraphQLError('first must be 50 or less',
    { extensions: { code: 'BAD_USER_INPUT' } });
  let list = [...posts].sort((a, b) =>
    b.createdAt.localeCompare(a.createdAt) || Number(b.id) - Number(a.id));
  if (after) {
    const [ts, id] = decodeCursor(after);
    list = list.filter(p => p.createdAt < ts || (p.createdAt === ts && Number(p.id) < Number(id)));
  }
  const page = list.slice(0, first);
  return {
    edges: page.map(node => ({ node, cursor: encodeCursor(node) })),
    pageInfo: { hasNextPage: list.length > first,
                endCursor: page.length ? encodeCursor(page.at(-1)) : null },
  };
},

Running posts(first: 3), then passing endCursor back as after, against a GraphQL Yoga server:

Code
page 1: [ '30', '29', '28' ]  { hasNextPage: true, endCursor: 'MjAyNi0xMC0wMVQwMDoyNzowMC4wMDBafDI4' }
page 2: [ '27', '26', '25' ]
first: 500 -> {"message":"first must be 50 or less","path":["posts"],"extensions":{"code":"BAD_USER_INPUT"}}

The cursor is opaque to clients (here base64url of 2026-10-01T00:27:00.000Z|28). Capping first matters even more in GraphQL than in REST: without it, one query could request every post and every comment on each.

Practical notes on GraphQL pagination

  • totalCount is optional and can be expensive on large tables. Add it only when screens need it, possibly as an estimate.
  • Use connections for any list that can grow, even if it's small today. Short fixed lists (a user's three addresses) can stay plain lists.
  • Client libraries understand connections: Relay and Apollo Client can merge pages automatically for infinite scrolling.
  • Offset arguments (page, limit) can be offered alongside for admin screens that need page numbers.

Check yourself

Edges wrap each item (the node) with its cursor and any relationship data; pageInfo says whether more items exist and where to continue.

It passes the previous response's pageInfo.endCursor as the after argument, with the same first size, and checks pageInfo.hasNextPage to know when to stop.

Without a cap, a single query can request a million items, and nested lists multiply the cost, such as 1,000 users each with 1,000 posts. Enforce a maximum, like 100, and reject or clamp larger values.

Counting all matching rows can be expensive on large tables. Offer it as an optional field so only clients that display totals pay for it.

To make them opaque, so clients treat them as tokens and the server can change their contents without breaking anyone.