Pagination

This page has been deprecated and is no longer maintained.

Refer to the introduction for up-to-date pagination information.

Endpoints which return a list of objects use pagination. Pagination allows a connection to request a part of the list, receiving an array of results and a next_cursor in the response. The connection can use the next_cursor in another request to receive the next part of the list. Using this technique, the connection can continue to make requests to receive the whole list (or just the parts the connection needs).

Requests

Each paginated endpoint accepts the following request parameters:

Parameter	Type	Description
start_cursor	string (optional)	A cursor returned from a previous response, used to request the next page of results. Treat this as an opaque value. Default: undefined, which indicates to return results from the beginning of the list.
page_size	number (optional)	The number of items from the full list desired in the response. Default: 100Maximum: 100 The response may contain fewer than this number of results.

Parameter location varies by endpoint

For endpoints using the HTTP GET method, these parameters are accepted in the request query string. For endpoints using the HTTP POST method, these parameters are accepted in the request body.

Responses

Responses from paginated endpoints contain the following properties:

Property	Type	Description
has_more	boolean	When the response includes the end of the list, false. Otherwise, true.
next_cursor	string	Only available when has_more is true. Used to retrieve the next page of results by passing the value as the start_cursor parameter to the same endpoint.
results	array of endpoint-dependent objects	The page, or partial list, or results.
object	string	Always list.
type	string (enum)	Type of the objects in results. Possible values include "block", "page", "user", "database", "property_item", "page_or_database", "view".
{type}	Pagination Type Object (see below)	An object containing a type-specific pagination information.

Pagination Type Object

Responses from paginated endpoints have keys corresponding to the value of type. Under the key is an object with type-specific pagination information. "block", "page", "user", "database" and "page_or_database" pagination type objects are empty objects. See Property item object endpoint for a description of "property_item" pagination type object.

Paginated endpoints

Query a data source

List databases

Retrieve a page property item

Retrieve block children

List all users

List views

Create a view query

Get view query results

Search