Paginated Results

This guide explains hot to handle paginated results in Lens.

Lens API uses cursor-based pagination to navigate through lists of results. This is crucial for both performance and user experience, as it allows the API to return only the data required at a given time.

Anatomy of a Response

With Type representing the item type being queried, all paginated queries return a Paginated<Type>Result object:

GraphQL
TypeScript

PaginatedTypeResulttype PaginatedTypeResult {  items: [Type!]!
  pageInfo: PaginatedResultInfo!}

where items contains the current page of results and pageInfo contains information about the pagination state:

GraphQL
TypeScript

PaginatedResultInfotype PaginatedResultInfo {  prev: Cursor  next: Cursor}

The Cursor is an opaque Scalar that can be used to fetch a different page of results.

Anatomy of a Request

All paginated queries accepts two optional parameters: pageSize and cursor.

GraphQL
TypeScript

input Request {  pageSize: PageSize  cursor: Cursor}

where

pageSize determines the number of items to return per page.
cursor is the value of the next or prev field from a previous response.

The meaning of prev and next depends on the query and the sorting order. For example, when sorting by creation date with most recent first, prev will return newer items and next will return older items.

Examples

GraphQL
React
TypeScript

Let's say you want to fetch the first page of posts by a specific author:

Queryquery {  posts(request: { filter: { authors: ["0x1234…"] }, pageSize: FIFTY }) {    items {      ... on Post {        ...Post      }
      ... on Repost {        ...Repost      }    }    pageInfo {      prev      next    }  }}

The response will contain the first page of posts and a next cursor:

Page 1{  "data": {    "posts": {      "items": [        /* ... */      ],      "pageInfo": {        "prev": null,        "next": "SGVsbG8hIQ=="      }    }  }}

To fetch the next page of posts, use the next cursor:

Queryquery {  posts(    request: {      filter: { authors: ["0x1234…"] }      pageSize: FIFTY      cursor: "SGVsbG8hIQ=="    }  ) {    items {      ... on Post {        ...Post      }
      ... on Repost {        ...Repost      }    }    pageInfo {      prev      next    }  }}

The response will contain the second page of posts and updated next and prev cursors:

Page 2{  "data": {    "posts": {      "items": [        /* ... */      ],      "pageInfo": {        "prev": "U3RyaW5nIQ==",        "next": "V2VsY29tZSE="      }    }  }}

That's it—you've just learned how to use paginated results.