Working with pagination

All of Medallion's endpoints that return lists of objects use so-called "limit-offset" pagination, meaning that you include the maximum number of objects you want in a given call (the "limit") plus the starting point for that call (the "offset").

🚧

Note: all endpoints that return lists of objects enforce pagination, meaning that the default limit is applied if none is specified. The default (and maximum) limit is typically 100 objects per request, though a handful of endpoints will allow a higher limit to better serve their use cases.

When a list endpoint is called, Medallion's API will return an object that contains the total number of objects, the URL to get the next batch of objects (if applicable), the URL to get the previous batch of objects (if applicable), and the objects in this batch. For example, if a given request would fetch 500 items in total, then setting limit=100&offset=100 would return the following object:

{
  "count": 500,
  "next": "....?limit=100&offset=200",
  "previous": "...?limit=100&offset=0",
  "results": [
    {},
    {},
    ....
    ]
}

The following Python snippet demonstrates how to fetch all items (here taken to be Providers) that match a given request using the next field:

import requests

url = "http://localhost:8000/api/v1/org/providers/"

headers = {
    "Accept": "application/json",
    "x-api-key": "APIKEY",
}

response = requests.get(url, headers=headers)

# check for any HTTP errors
response.raise_for_status()

response_json = response.json()
providers = response_json["results"]

while response_json["next"]:
  response = requests.get(response_json["next"], headers=headers)
  response.raise_for_status()
  response_json = response.json()
  providers += response_json["results"]
  
assert len(providers) == response_json["count"]

Note that you can also specify the limit and offset parameters manually to fetch a specific chunk:

import requests

url = "http://localhost:8000/api/v1/org/providers/"

headers = {
    "Accept": "application/json",
    "x-api-key": "APIKEY",
}

params = {
  "limit": 100,
  "offset": 200,
}

# will fetch providers 201 -- 300
response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
chunk = response.json()["results"]