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
  }

Specifically for the /users endpoint that retrieves a list of users within a school, creators who have more than 10,000 users in their school can paginate using a search_after query parameter.

To begin, you can add ?search_after={ID of the last user on the first request} within the first page, which will be used to navigate to the next page of results. The following search_after value can be found within the pagination meta. You must continue to use the sort value with a search_after query parameter in your next request URL to retrieve the next set of results of users. Within the pagination meta, there will be another boolean key-value pair called has_more_results, which will inform you that there are more results to return.

Creators with over 10,000 users can continue to use the page parameter, which will work up to the 10,000th result. However, you will need to switch to using search_after to retrieve any results past 10,000.

It’s important to note that for creators who have more than 10,000 users and search using search_after will see a different pagination metadata attached to the results. It will no longer include from and to within the meta object.

For example, if you have more than 10,000 users and want to fetch beyond the 10,000th user, your request will look like this:

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

The pagination meta will display:

"meta": {
        "page": 1,
        "total": 10156,
        "number_of_pages": 508,
        "has_more_results": true,
        "search_after": [
            10520
        ],
        "per_page": 20
    }
}

In this request, the LAST_SORTED_VALUE should be replaced with the actual last sorted value from the current response of your results. The value is sorted by user ID, which will always be an integer.