Core

Paging

View as Markdown

For resources that return many instances, the API will return partial “pages” of results. These results will contain meta information about the entire list of results you can use to see more of the list.

AttributeTypeDescription
uristringThe current page’s URI.
first_page_uristringThe first page in the result set’s URI.
next_page_uristringThe next page in the result set’s URI.
previous_page_uristringThe previous page in the result set’s URI.
pageintegerThe current page number, using zero-based number (so the first page would be 0).
page_sizestringThe number of results per page. The last page may have fewer items.

Here is an example of a paged result of messages with one message per page.

1{
2  "uri": "/api/laml/2010-04-01/Accounts/446e9986-0848-4d46-a617-48793c5f5e07/Messages?Page=0&PageSize=1",
3  "first_page_uri": "/api/laml/2010-04-01/Accounts/446e9986-0848-4d46-a617-48793c5f5e07/Messages?Page=0&PageSize=1",
4  "next_page_uri": "/api/laml/2010-04-01/Accounts/446e9986-0848-4d46-a617-48793c5f5e07/Messages?Page=1&PageSize=1&PageToken=PA95f7fba1-aeb7-4750-9092-47525b7a7cad",
5  "previous_page_uri": null,
6  "page": 0,
7  "page_size": 1,
8  "messages": [
9    {
10      "account_sid": "446e9986-0848-4d46-a617-48793c5f5e07",
11      "api_version": "2010-04-01",
12      "body": "Hello World!",
13      "num_segments": 1,
14      "num_media": 0,
15      "date_created": "Tue, 14 Aug 2018 19:37:39 +0000",
16      "date_sent": "Tue, 14 Aug 2018 19:37:41 +0000",
17      "date_updated": "Tue, 14 Aug 2018 19:37:44 +0000",
18      "direction": "outbound-api",
19      "error_code": null,
20      "error_message": null,
21      "from": "+15551234567",
22      "price": 0.005,
23      "price_unit": "USD",
24      "sid": "8a8e5ec4-071a-408e-948c-2429da869cc9",
25      "status": "delivered",
26      "to": "+15557654321",
27      "uri": "/api/laml/2010-04-01/Accounts/446e9986-0848-4d46-a617-48793c5f5e07/Messages/8a8e5ec4-071a-408e-948c-2429da869cc9",
28      "subresource_uris": {
29        "media": "/api/laml/2010-04-01/Accounts/446e9986-0848-4d46-a617-48793c5f5e07/Messages/8a8e5ec4-071a-408e-948c-2429da869cc9/Media"
30      }
31    }
32  ]
33}
Always use the latest next and previous page URIs

You should always use the returned next_page_uri or previous_page_uri when traversing to the next or previous page in the result set. This will ensure you properly page through all of resources and your result set is not affected by new resources being created, or paging scheme changing.