Some API endpoints return lists of objects, and to handle large datasets efficiently, they use pagination.
Examples of endpoints using pagination: List Signature Requests, List Templates, etc.

Note: Not all listing endpoints support pagination. Refer to the API reference for specific details on each endpoint.

This method allows seamless handling of large datasets, ensuring clarity and consistency in retrieving paginated results.

🛠️ How Pagination Works

Pagination is a method used to divide large sets of results into smaller, easier-to-handle chunks. In our API, each page can include up to 100 records.

When an endpoint supports pagination, the response includes:

data: An array containing the requested results.
A meta field: an object containing metadata about the response, including a next_cursor key.

The next_cursor acts as a pointer to the next page of results. If it’s not null, it means there are more results available. You can use this cursor to fetch the next page of data.

{
  "meta": {
    "next_cursor": "MTYzMDk0MDg3My43Nj..."
  },
  "data": [
    // Results here
  ]
}

If next_cursor is null, you have reached the end of the dataset:

{
  "meta": {
    "next_cursor": null
  },
  "data": [
    // Results here
  ]
}

🔄 Fetching the Next Page

To retrieve the next set of results:

Extract the next_cursor value from the meta object in the response.
Include it as a query parameter using after in your next API request.

Example API Query for the Next Page:

GET /signature_requests?after=MTYzMDk0MDg3My43Nj...

This approach ensures you can reliably retrieve the next batch of results.

Adjusting the Number of Records with the `limit` Parameter

Some endpoints allow you to customize the number of records returned per page using the limit query parameter.
If no limit parameter is provided, the default limit is 100.

📊 Real Example: Retrieving Paginated Signature Requests

In this example, we have a dataset with 101 Signature Requests. In order to retrieve all of them with the List Signature Requests endpoint, we will have to perform two queries. One to get the first 100 Signature Requests, then a second to get the remaining Signature Requests.

1) First query without using a cursor as parameter:

GET /signature_requests

{
    "meta": {
        "next_cursor": "MTY3MjY2NTc2MC42NDc2NzQgYTgwYTNkMjYtNzA3Ny00ZWMyLWEzMTMtNjk1MDdlOGRlZjQ1"
    },
    "data": [
        {
            "approvers": [],
            "id": "ac50edf7-076e-4f1b-b680-0797e6a1135d",
            "source": "public_api",
            "status": "draft",
            "name": "The name of your Signature Request",
            "created_at": "2023-01-03T10:37:32+00:00",
            "email_custom_note": null,
            "ordered_signers": false,
            "timezone": "Europe/Paris",
            "reminder_settings": null,
            "expiration_date": "2023-07-03T21:59:00+00:00",
            "delivery_mode": "email",
            "documents": [
                {
                    "id": "c9e77f4e-60a6-4a0d-abc9-d8c210fa1521",
                    "nature": "signable_document"
                }
            ],
            "signers": [
                {
                    "id": "3cd1a547-b207-4c29-a3b6-f98bb9997415",
                    "status": "initiated"
                },
                {
                    "id": "bb79a1d1-dcc1-45e8-9418-e864bf332ae1",
                    "status": "initiated"
                },
                {
                    "id": "a7bcd14d-7871-4af9-95dc-fbcdefc00fd7",
                    "status": "initiated"
                }
            ],
            "external_id": null,
            "custom_experience_id": null,
            "sender": null
        },
      
				//...+ 99 more Signature Requests
    ]
}

2) Then we will fetch the next result page using the cursor returned by the last query:

GET /signature_requests?after=MTY3MjY2NTc2MC42NDc2NzQgYTgwYTNkMjYtNzA3Ny00ZWMyLWEzMTMtNjk1MDdlOGRlZjQ1

{
    "meta": {
        "next_cursor": null
    },
    "data": [
        {
            "approvers": [],
            "id": "aac08775-440e-4514-a14e-bf330f6dd74d",
            "source": "public_api",
            "status": "draft",
            "name": "The name of your Signature Request",
            "created_at": "2023-01-02T10:10:32+00:00",
            "email_custom_note": null,
            "ordered_signers": false,
            "timezone": "Europe/Paris",
            "reminder_settings": null,
            "expiration_date": "2023-07-02T21:59:00+00:00",
            "delivery_mode": "email",
            "documents": [
                {
                    "id": "04ee8759-4fce-4f1f-8e9e-6a4b0e7f2461",
                    "nature": "signable_document"
                }
            ],
            "signers": [
                {
                    "id": "4c3bf3ee-474e-4cb0-ba8f-897d5b330fde",
                    "status": "initiated"
                },
                {
                    "id": "44414f9f-f814-448f-8044-cb8e20f6c46b",
                    "status": "initiated"
                },
                {
                    "id": "f537b1ea-e4f1-4fc7-9347-dada5d9ff049",
                    "status": "initiated"
                }
            ],
            "external_id": null,
            "custom_experience_id": null,
            "sender": null
        }
    ]
}

The meta data next_cursor is now null, which means that there is no record left.

🛠️ How Pagination Works

🔄 Fetching the Next Page

Adjusting the Number of Records with the limit Parameter

📊 Real Example: Retrieving Paginated Signature Requests

Adjusting the Number of Records with the `limit` Parameter