---
title: "Page GraphQL lists as cursor connections · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/graphql-and-grpc/graphql-connections
id: API-83
level: Recommended
updated: 2026-10-22
tokens: 952
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Page GraphQL lists as cursor connections

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [GraphQL and gRPC](https://agentwranglers.se/playbook/api-design/graphql-and-grpc.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: API-83
- Level: Recommended
- Chapter: [GraphQL and gRPC](https://agentwranglers.se/playbook/api-design/graphql-and-grpc.md)
- Rule: Return every list that can grow past 100 items as a connection with `edges`, `node`, `cursor` and `pageInfo`. Require a `first` or `last` argument with a cap.
- Check: Introspection on the test copy shows no list field of an object type without `first` or `last`. A query with `first: 10000` returns an error or at most the capped number of items.
- How: An unpaged list field lets one query fetch a million rows. graphql.org recommends cursor connections, and the Relay connection format is the common shape. Keep cursors opaque, as [page lists with cursors](https://agentwranglers.se/playbook/api-design/lists/cursor-pagination.md) says. Cap `first` the same way as [cap the page size](https://agentwranglers.se/playbook/api-design/lists/page-size-limit.md), and count it in the query cost limit.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Plain text example

```graphql
type Query {
  invoices(first: Int = 20, after: String): InvoiceConnection!
}

type InvoiceConnection {
  edges: [InvoiceEdge!]!
  pageInfo: PageInfo!
}

type InvoiceEdge { cursor: String! node: Invoice! }
type PageInfo { endCursor: String hasNextPage: Boolean! }
```

### JavaScript example

```js
const MAX_PAGE = 100;

const invoices = async (_, { first = 20, after }, ctx) => {
  const limit = Math.min(first, MAX_PAGE);
  const rows = await ctx.db.invoicesAfter(ctx.user.id, decodeCursor(after), limit + 1);
  const edges = rows.slice(0, limit).map(node => ({ node, cursor: encodeCursor(node.id) }));
  return { edges, pageInfo: { endCursor: edges.at(-1)?.cursor ?? null, hasNextPage: rows.length > limit } };
};
```

### Python example

```python
MAX_PAGE = 100

def resolve_invoices(info, first: int = 20, after: str | None = None):
    limit = min(first, MAX_PAGE)
    rows = info.context.db.invoices_after(info.context.user.id, decode_cursor(after), limit + 1)
    edges = [{"node": row, "cursor": encode_cursor(row.id)} for row in rows[:limit]]
    return {"edges": edges, "page_info": {"end_cursor": edges[-1]["cursor"] if edges else None, "has_next_page": len(rows) > limit}}
```

## Sources

- [GraphQL, Pagination](https://graphql.org/learn/pagination/)

## Related rules

- API-21 [Page lists with cursors](https://agentwranglers.se/playbook/api-design/lists/cursor-pagination.md) in API design
- API-22 [Cap the page size](https://agentwranglers.se/playbook/api-design/lists/page-size-limit.md) in API design

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/api-design/graphql-and-grpc/graphql-connections">Agent Wranglers API design playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Deprecate GraphQL fields before you remove them](https://agentwranglers.se/playbook/api-design/graphql-and-grpc/graphql-deprecation.md)
- Next: [Load related records in batches](https://agentwranglers.se/playbook/api-design/graphql-and-grpc/graphql-batching.md)
- [GraphQL and gRPC](https://agentwranglers.se/playbook/api-design/graphql-and-grpc.md)