Pagination

When an endpoint returns more items than can be contained in a single response, the data is split and returned into multiple pages. By default, an endpoint returns 25 items per page—so if there are more than 25 items to return, the data will be split across pages.

Only certain endpoints support pagination (e.g., /courses, /webhooks/{webhook_id}/events, /pricing_plans, and /transactions).

You can change the default pagination response format by adding per and page parameters to your request.

  • per - Set the number of results to be returned per page.
  • page - Set the page number to be returned.

For example, your school might have 50 total courses. If you make a request to the /courses endpoint to fetch all courses, the return data will be split into multiple pages as you can only return 20 maximum items per page.

If you want to only return 5 items (i.e., courses) per page, you can add the per parameter to your request:

curl --request GET \
     --url 'https://developers.teachable.com/v1/courses?per=5' \
     --header 'Accept: application/json' \
     --header 'apiKey: API-KEY-HERE'

The request above would return data for the first page of items (i.e., the first 5 courses). You can then use the page parameter to adjust which page number to return. For example, adding a parameter page=2 to the above request would return the second page of courses (i.e., courses 6 through 10).

curl --request GET \
     --url 'https://developers.teachable.com/v1/courses?page=2&per=5' \
     --header 'Accept: application/json' \
     --header 'apiKey: API-KEY-HERE'

When an endpoint returns data across multiple pages, the return data will include a meta object that provides information on the pagination of the data:

-total - The total number of items
-page - The current page
-from - First item number on current page
-to - Last item number on current page
-per_page - The number of items displayed per page
-number_of_pages - The total number of pages

This means that for our example call above, the meta object in the return data would be:

"meta": {
    "total": 50,
    "page": 2,
    "from": 6,
    "to": 10,
    "per_page": 5,
    "number_of_pages": 10
  }