> ## Documentation Index
> Fetch the complete documentation index at: https://dev.ownright.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> For responses that return lists it's important to understand how we paginate

The Ownright Developer Platform uses the GraphQL "Connection" pattern for pagination —
a powerful and flexible way to request data in chunks while maintaining full control over
ordering and navigation.

If you're used to page and per\_page style pagination, this might feel different at first,
but it offers more precision and consistency — especially in real-time environments where
data can change frequently.

## 🔄 What are GraphQL connections?

Connections are a GraphQL pattern for handling lists of objects (like referrals or matters)
in a standardized way. Instead of simple arrays, connections return a structured object with:

**A list of edges, each containing:**

<ul>
  <li>A node (the item you care about)</li>
  <li>A cursor (a pointer used for pagination)</li>
</ul>

**A pageInfo object that helps you know:**

<ul>
  <li>If there's a `hasNextPage` or `hasPreviousPage`</li>
  <li>What the `startCursor` and `endCursor` are for the current page</li>
</ul>

This model helps avoid missing or duplicate items when new data is created during pagination.

## 📦 Example paginated query

Let's say you want to fetch a list of items, 10 at a time:

```graphql theme={null}
query FetchMatters {
  matters(first: 10) {
    edges {
      node {
        id
        kind
        ...
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

When you get the response, you'll receive a list of items, and if `hasNextPage` is true,
you can request the next page using the `endCursor`:

```graphql theme={null}
query FetchMoreMatters {
  matters(first: 10, after: "cursor_from_previous_page") {
    ...
  }
}
```

This gives you cursor-based pagination, which is more reliable than
offset-based pagination when the data is constantly changing.

## 🧠 Common use cases

Here are a few common ways to use connections:

<ul>
  <li>List all records using a query with `first: N` and pagination</li>
  <li>Build an activity feed by scrolling through updates</li>
  <li>Export historical data one page at a time for internal reporting</li>
  <li>Sync new records incrementally by storing the last cursor you've seen</li>
</ul>

## 📚 Learn more about GraphQL connections

If you're new to GraphQL pagination, here are some great resources:

<ul>
  <li>
    [GraphQL Cursor Connections
    Specification](https://relay.dev/graphql/connections.htm) – the original
    spec
  </li>

  <li>
    [Apollo Pagination
    Docs](https://www.apollographql.com/docs/react/pagination/overview/) –
    practical client-side usage
  </li>

  <li>
    [Hasura Pagination Primer](https://hasura.io/learn/graphql/pagination/) –
    friendly intro with visual examples
  </li>
</ul>

## 💡 Tips for implementation

<ul>
  <li>Always check `pageInfo.hasNextPage` before paginating</li>

  <li>
    Don't assume cursors are sequential strings — treat them as opaque tokens
  </li>

  <li>Use cursors to resume pagination if a sync job is interrupted</li>

  <li>
    Avoid using GraphQL offset or skip patterns — they're not supported in our
    APIs
  </li>
</ul>