Pagination

Pagination allows you to retrieve a subset of records from a collection.

Request format

The JSON:API implements pagination using page[limit] to specify the maximum number of records to return and page[offset] to skip a specific number of records.

GET /v1/rest/<subgraph-name>/<model-name>?page[limit]=<limit>&page[offset]=<offset>

Parameter	Description	Example
subgraph-name	Name of your subgraph.	"default"
model-name	Name of your model.	"Users"
limit	Maximum number of records to return.	10
offset	Number of records to skip.	20

Examples

Limit

Fetch the first two articles.

Request:

GET /v1/rest/default/Articles?page[limit]=2

Response:

{
  "data": [
    {
      "type": "Articles",
      "id": "1",
      "attributes": {
        "title": "First Article",
        "content": "Content of first article"
      }
    },
    {
      "type": "Articles",
      "id": "2",
      "attributes": {
        "title": "Second Article",
        "content": "Content of second article"
      }
    }
  ]
}

Using offset and limit

Request:

GET /v1/rest/default/Articles?page[limit]=2&page[offset]=2

Response:

{
  "data": [
    {
      "type": "Articles",
      "id": "3",
      "attributes": {
        "title": "Third Article",
        "content": "Content of third article"
      }
    },
    {
      "type": "Articles",
      "id": "4",
      "attributes": {
        "title": "Fourth Article",
        "content": "Content of fourth article"
      }
    }
  ]
}

Combining with other parameters

Pagination can be combined with other query parameters like sort and include:

Example

Fetch the second page of articles, sorted by creation date in descending order, and include the author information.

Request:

GET /v1/rest/default/Articles?page[limit]=2&page[offset]=2&sort=-created_at&include=author

Response:

{
  "data": [
    {
      "type": "Articles",
      "id": "3",
      "attributes": {
        "title": "Third Article",
        "content": "Content of third article",
        "created_at": "2023-01-03T12:00:00Z"
      },
      "relationships": {
        "author": {
          "data": {
            "type": "Authors",
            "id": "3"
          }
        }
      }
    },
    {
      "type": "Articles",
      "id": "4",
      "attributes": {
        "title": "Fourth Article",
        "content": "Content of fourth article",
        "created_at": "2023-01-02T12:00:00Z"
      },
      "relationships": {
        "author": {
          "data": {
            "type": "Authors",
            "id": "4"
          }
        }
      }
    }
  ],
  "included": [
    {
      "type": "Authors",
      "id": "3",
      "attributes": {
        "name": "Author Three"
      }
    },
    {
      "type": "Authors",
      "id": "4",
      "attributes": {
        "name": "Author Four"
      }
    }
  ]
}