Pagination

All top-level API resources have support for bulk fetches via "list" API methods. For instance, you can list the Multi-Factor Authentication Methods Available to your Application, list events, and list logs. These list API methods share a common structure, taking at least these three parameters: limit, starting_after, and ending_before.

The response of a list API method represents a single page in a reverse chronological stream of objects. If you do not specify starting_after or ending_before, you will receive the first page of this stream, containing the newest objects. You can specify starting_after equal to the object ID value (see below) of an item to retrieve the page of older objects occurring immediately after the named object in the reverse chronological stream. Similarly, you can specify ending_before to receive a page of newer objects occurring immediately before the named object in the stream. Objects in a page always appear in reverse chronological order. Only one of starting_after or ending_before may be used.

Our client libraries offer auto-pagination helpers to easily traverse all pages of a list.

Parameters

  • Name
    limit
    Type
    optional, default is 10
    Description

    A limit on the number of objects to be returned, between 1 and 100.

  • Name
    starting_after
    Type
    optional
    Description

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

  • Name
    ending_before
    Type
    optional
    Description

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

List Response Format

  • Name
    object
    Type
    string, value is 'list'
    Description

    A string describing the object type returned.

  • Name
    data
    Type
    array
    Description

    An array containing the actual response elements, paginated by any request parameters.

  • Name
    has_more
    Type
    boolean
    Description

    Whether or not there are more elements available after this set. If false, this set comprises the end of the list.

  • Name
    url
    Type
    string
    Description

    The URL for accessing this list.

RESPONSE

{
  "object": "list",
  "url": "/v1/hello",
  "has_more": false,
  "data": [
    {
      "id": "hello_S1wKRW1maeBYtE",
      "object": "hello",
      "created": 1671729638,
      "hello_settings": {
        "random_hello": false,
        "requires_hello": false
      },
      "livemode": false,
      "metadata": {},
    },
    {...},
    {...}
  ]
}

Some top-level API resource have support for retrieval via "search" API methods.

DevRIFT's search API methods utilize cursor-based pagination via the page request parameter and next_page response parameter. For example, if you make a search request and receive "next_page": "pagination_key" in the response, your subsequent call can include page=pagination_key to fetch the next page of results.

Our client libraries offer auto-pagination helpers to easily traverse all pages of a search result.

Search Request Format

  • Name
    query
    Type
    REQUIRED
    Description

    The search query string.

  • Name
    limit
    Type
    optional
    Description

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • Name
    page
    Type
    optional
    Description

    A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.

Search Response Format

  • Name
    object
    Type
    string, value is 'search_result'
    Description

    A string describing the object type returned.

  • Name
    url
    Type
    string
    Description

    The URL for accessing this list.

  • Name
    has_more
    Type
    boolean
    Description

    Whether or not there are more elements available after this set. If false, this set comprises the end of the list.

  • Name
    data
    Type
    array
    Description

    An array containing the actual response elements, paginated by any request parameters.

  • Name
    next_page
    Type
    string
    Description

    A cursor for use in pagination. If has_more is true, you can pass the value of next_page to a subsequent call to fetch the next page of results.

  • Name
    total_count
    Type
    optional positive integer or zero
    Description

    The total number of objects that match the query, only accurate up to 10,000. This field is not included by default.

RESPONSE

{
  "object": "list",
  "url": "/v1/hello/search",
  "has_more": false,
  "data": [
    {
      "id": "hello_S1wKRW1maeBYtE",
      "object": "hello",
      "created": 1671729638,
      "hello_settings": {
        "random_hello": false,
        "requires_hello": false
      },
      "livemode": false,
      "metadata": {
        "hello_messages": 1
      },
    },
    {...},
    {...}
  ]
}

Auto Pagination

Our libraries support auto-pagination. This feature easily handles fetching large lists of resources without having to manually paginate results and perform subsequent requests.

Auto-paginating without ending_before will iterate in reverse chronological order. Auto-paginating with ending_before will iterate in forwards chronological order, despite the fact that the order of items in a list API response is always reverse chronological.

# The auto-pagination feature is specific to DevRIFT's
# libraries and cannot be used directly with curl.