Developers

Pagination

Review lists come in pages. Ask for up to 100 reviews at a time, then pass meta.next_cursor back as cursor until meta.has_more is false.

How cursors work

NameWhereWhat it does
limitqueryPage size. Reviews: 1 to 100, 25 if you leave it out. Public reviews (/v1/public/reviews): 1 to 50, default 10. Other lists say their own range in the reference
cursorqueryThe meta.next_cursor of the previous page. Opaque: do not build or change it. It only works with the same sort (and should be sent with the same filters)
meta.next_cursorresponseThe cursor of the next page, null on the last one
meta.has_moreresponsetrue while another page follows
meta.totalresponseThe number of matching reviews, only when you send include_total_quantity=true (it costs a count, so leave it off when you just walk the list)
The end of one page
{
  "data": [ { "uuid": "…", "rating": 5, "site": "google", "…": "…" } ],
  "meta": {
    "limit": 100,
    "sort": "newest",
    "next_cursor": "eyJ…",
    "has_more": true
  }
}

Walk every page

The same filters and sort on every request, the next cursor each time:

Every review, page by page
# First page
curl -G https://app.grades.com/api/v1/companies/COMPANY_UUID/reviews \
  -H "Authorization: Bearer $GRADES_API_KEY" \
  --data-urlencode "limit=100"

# Next page: meta.next_cursor from the answer above, same filters and sort
curl -G https://app.grades.com/api/v1/companies/COMPANY_UUID/reviews \
  -H "Authorization: Bearer $GRADES_API_KEY" \
  --data-urlencode "limit=100" \
  --data-urlencode "cursor=NEXT_CURSOR"

The JavaScript, Python and PHP samples reuse API and headers (or $grades) from the quickstart.

What a walk guarantees

  • Pages are keyset pages, not offsets: every sort ends with the review's id, so the order is total and a page never repeats or skips because reviews arrived meanwhile.
  • A walk returns each review that existed when it began, and whose sort key did not change, exactly once. Reviews created during the walk are not included: start a new walk from the first page to see them.
  • A review whose sort key changes during the walk (a rating edit while you page by rating, a corrected publish date while you page by date) can appear twice or not at all. Dedupe by uuid, and use sort=newest or oldest for syncs.
  • To keep a copy in sync, store the newest published_at you have and ask with start_date next time, or let webhooks tell you about new and changed reviews.

Conditional requests

Every successful JSON GET made with a key or token carries a weak ETag. Send it back as If-None-Match: an unchanged answer is 304 Not Modified with no body. A 304 still counts toward the rate limit. Tags are per credential, so the same data read with another key has another tag.