Pagination

Every endpoint that returns a list returns it one page at a time, in the same envelope.

The envelope

curl -H "X-Api-Key: $MOTORBAY_API_KEY" \
  "https://api.motorbay.app/v1/kinds?page=1&pageSize=3"

{
  "data": [
    { "id": "1", "name": "Personbil", "originalName": "Personbil" },
    { "id": "2", "name": "Stor personbil", "originalName": "Stor personbil" },
    { "id": "3", "name": "Varebil", "originalName": "Varebil" }
  ],
  "metadata": { "page": 1, "pageSize": 3, "totalCount": 15, "totalPages": 5 }
}

Page and page size

• page starts at 1. The default is 1.
• pageSize defaults to 10. It can be at most 50 on most lists, and at most 20 on vehicle search (GET /v1/vehicles).

A value out of range is a 400 with the code ValidationFailed. The errors field names the rule: PageOutOfRange for a page below 1, PageSizeOutOfRange for a pageSize below 1 or above the maximum.

Reading every page

Ask for pages until page equals totalPages:

page=1
while :; do
  body=$(curl -s -H "X-Api-Key: $MOTORBAY_API_KEY" \
    "https://api.motorbay.app/v1/colors?page=$page&pageSize=50")
  echo "$body" | jq -c '.data[]'
  total=$(echo "$body" | jq '.metadata.totalPages')
  [ "$page" -ge "$total" ] && break
  page=$((page + 1))
done

A page past the last page of a list that has items is a 400 with PageOutOfRange, not an empty page. A list with no items is a 200 with "data": [], totalCount 0 and totalPages 0, whatever page you ask for.

Sorting vehicle search

GET /v1/vehicles takes sortBy. A leading - sorts descending:

Vehicles without the value come last in either direction. Ties are broken by id, so the order is stable from page to page. Any other value is a 400 with the rule SortByInvalid.

Search stops at 10,000 results

Vehicle search returns at most 10,000 results for one query: page × pageSize may be at most 10,000. With the largest page size of 20, the last page you can reach is page 500. Asking for more is a 400 with the rule SearchTooDeep.

totalCount still tells you how many vehicles match. To reach the rest, narrow the search. The filters combine with AND:

curl -H "X-Api-Key: $MOTORBAY_API_KEY" \
  "https://api.motorbay.app/v1/vehicles?makeId=10279&fromModelYear=2020&toModelYear=2020&pageSize=20"

Get the IDs for these filters from /v1/makes, /v1/kinds, /v1/usages and /v1/colors.

Changes while you page

The data changes when a new weekly extract is imported. If you page through a large result across an import, items can move between pages. Check GET /v1/dataset before and after, and start again if importedAt changed. See Data source and freshness.