# Pagination ## Response format Every operation that returns a list returns one page at a time, in the same format: ```json { "data": [ { "id": "show_5f8d0d55b54764421b7156c3" } ], "next_cursor": "c2hvd181ZjhkMGQ1NWI1NDc2NDQyMWI3MTU2YzM" } ``` | Field | Meaning | |---|---| | `data` | The items on this page. | | `next_cursor` | Pass this value as `cursor` to get the next page. `null` on the last page. | ## Parameters | Parameter | Meaning | |---|---| | `limit` | How many items a page holds. From 1 to 100. The default is 25. Show search is the exception: it returns 15 shows a page and takes no other size. | | `cursor` | The `next_cursor` value from the previous page. Leave it out for the first page. | ## Read a whole list 1. Call the operation without `cursor`. 2. If `next_cursor` isn't `null`, call again with `cursor` set to it and every other parameter unchanged. 3. Repeat until `next_cursor` is `null`. ```bash curl "https://api.gumball.fm/v1/me/shows?limit=100" \ -H "Authorization: Bearer gum_YOUR_KEY" curl "https://api.gumball.fm/v1/me/shows?limit=100&cursor=c2hvd181ZjhkMGQ1NWI1NDc2NDQyMWI3MTU2YzM" \ -H "Authorization: Bearer gum_YOUR_KEY" ``` ## Rules - A cursor is an opaque string. Don't build one or read meaning into it. - A cursor belongs to the list that returned it. Pass it back to that list only, with the same filters. A value that isn't a cursor answers `invalid_request`. - A list has no total count. - Each list has one fixed order, which the [API reference](https://gumball.fm/developers/reference) states per operation.