{"_id":"56c51effba4a540d0091b9bb","parentDoc":null,"version":{"_id":"564e5a9b1560880d008d30dc","project":"564e5930c3553e0d003e53d0","__v":27,"createdAt":"2015-11-19T23:26:19.166Z","releaseDate":"2015-11-19T23:26:19.166Z","categories":["564e5a9b1560880d008d30dd","566318e1f5ca460d00f41896","56631d08cd54d50d005015fa","56631d2a81ad7417006a202c","5668ba19fbd7680d009375f4","5668cb8b10bda80d00797ed9","5668cb9d10bda80d00797eda","56830d8a3f94e00d004e2a7a","56830d9072bb720d0091f594","56830d94cb4d190d0027698e","56830dc44aecbd0d00a464c5","569e90f3c9b43e0d00c4bab1","56a96d338791090d00113bab","56b12d8336d2580d00247877","56c36bf0a869d017002ea55b","56c36bf93d30210d00ea84bb","56c77749b935671700ff0304","56c7ab9e5652c217008e091a","56cb8bdad5c6241d00ef5e61","58aefce02470660f00b54539","58aefd0bebd7370f0078b954","59ca65ca4337830026edf24f","5c33cd9eb47ba20051ac8d64","5c33df728bec1d0063431c34","5c4783ef523219027055513a","5c4f35033400f3010203a999","5d1d0c9f19c3a0003aeb525a"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Foundation","version_clean":"2.0.0","version":"2"},"__v":3,"githubsync":"","project":"564e5930c3553e0d003e53d0","user":"564e5788230d7c1700c9073e","category":{"_id":"56a96d338791090d00113bab","__v":13,"pages":["56a96d492bb3910d000ee931","56c3cec2106c12170020db96","56c51da4ba4a540d0091b9b7","56c51dc3ba4a540d0091b9b9","56c51eb916c7190d00ff7b19","56c51ec2d7b9ed19008d1752","56c51eec668eb01900719bcd","56c51effba4a540d0091b9bb","56c51f1cf7c4da0d00614b02","56c51f2a8dc1c51900abc142","56c51f367de3580d00bdaf2a","56c67b6270e7660d004a8985","56c67b7cfd00bb0d0016daad"],"project":"564e5930c3553e0d003e53d0","version":"564e5a9b1560880d008d30dc","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-28T01:21:55.716Z","from_sync":false,"order":3,"slug":"patterns","title":"REST API"},"metadata":{"title":"","description":"","image":[]},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-18T01:31:43.700Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":8,"body":"Many [index endpoints](doc:endpoints#resources-index) will be paginated, meaning that only a certain number of resources will be returned at a time. The default is 25. You can override this by passing a `limit` parameter to set the maximum number of results, but cannot exceed 100. Specifying a number for `offset` sets the starting point for the result set, allowing you to fetch subsequent resources that are not in the initial set of results.\n\nEvery paginated endpoint's response contains four fields, as seen in the example below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"limit\\\": 25, // echoes the \\\"limit\\\" value that was used\\n  \\\"offset\\\": 0, // echoes the \\\"offset\\\" value that was used\\n  \\\"more\\\": true, // indicates if there are more resources available than were returned\\n  \\\"total\\\": 44 // the total number of resources matching the query\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Pagination response fields\"\n    }\n  ]\n}\n[/block]\nThe `more` field will always be `true` or `false`, indicating whether there are more resources matching the query than present in the response (because of the request's `limit`). If `true`, you may want to make subsequent requests with a different `offset` until `more` is `false` in order to retrieve all of the resources.\n\nThe `total` field is `null` by default. This behavior will provide the fastest response times when the total number of records is not important. If you need to know how many records match the query, pass a `total=true` parameter as part of the request and this field will be populated.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Maximum upper limit of pagination\",\n  \"body\": \"The REST API permits retrieving a maximum of 10000 records via pagination. That is to say, the sum of the `offset` and `limit` parameters cannot exceed 10000, or the REST API will respond with status 400.\\n\\nIf the `total` parameter is greater than 10000, then not all records in the set can be retrieved. As an alternative, one should constrain the results to under 10000 by [using a filter](filtering) and then adjust the filter to encompass more of the target set to be retrieved.\"\n}\n[/block]","excerpt":"","slug":"pagination","type":"basic","title":"Pagination"}
Many [index endpoints](doc:endpoints#resources-index) will be paginated, meaning that only a certain number of resources will be returned at a time. The default is 25. You can override this by passing a `limit` parameter to set the maximum number of results, but cannot exceed 100. Specifying a number for `offset` sets the starting point for the result set, allowing you to fetch subsequent resources that are not in the initial set of results. Every paginated endpoint's response contains four fields, as seen in the example below: [block:code] { "codes": [ { "code": "{\n \"limit\": 25, // echoes the \"limit\" value that was used\n \"offset\": 0, // echoes the \"offset\" value that was used\n \"more\": true, // indicates if there are more resources available than were returned\n \"total\": 44 // the total number of resources matching the query\n}", "language": "json", "name": "Pagination response fields" } ] } [/block] The `more` field will always be `true` or `false`, indicating whether there are more resources matching the query than present in the response (because of the request's `limit`). If `true`, you may want to make subsequent requests with a different `offset` until `more` is `false` in order to retrieve all of the resources. The `total` field is `null` by default. This behavior will provide the fastest response times when the total number of records is not important. If you need to know how many records match the query, pass a `total=true` parameter as part of the request and this field will be populated. [block:callout] { "type": "warning", "title": "Maximum upper limit of pagination", "body": "The REST API permits retrieving a maximum of 10000 records via pagination. That is to say, the sum of the `offset` and `limit` parameters cannot exceed 10000, or the REST API will respond with status 400.\n\nIf the `total` parameter is greater than 10000, then not all records in the set can be retrieved. As an alternative, one should constrain the results to under 10000 by [using a filter](filtering) and then adjust the filter to encompass more of the target set to be retrieved." } [/block]