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
| Name | Where | What it does |
|---|---|---|
limit | query | Page 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 |
cursor | query | The 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_cursor | response | The cursor of the next page, null on the last one |
meta.has_more | response | true while another page follows |
meta.total | response | The 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"
Every review, page by page
async function* allReviews(company, filters = {}) {
let cursor = null;
do {
const query = new URLSearchParams({ ...filters, limit: '100', ...(cursor ? { cursor } : {}) });
const res = await fetch(`${API}/companies/${company}/reviews?${query}`, { headers });
const body = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${body.detail}`);
yield* body.data;
cursor = body.meta.has_more ? body.meta.next_cursor : null;
} while (cursor);
}
for await (const review of allReviews('COMPANY_UUID', { min_rating: '4' })) console.log(review.uuid);Every review, page by page
def all_reviews(company, **filters):
params = {**filters, "limit": 100}
while True:
r = requests.get(f"{API}/companies/{company}/reviews", headers=headers, params=params, timeout=30)
r.raise_for_status()
page = r.json()
yield from page["data"]
if not page["meta"]["has_more"]:
break
params["cursor"] = page["meta"]["next_cursor"]
for review in all_reviews("COMPANY_UUID", min_rating=4):
print(review["uuid"])Every review, page by page
function all_reviews(GuzzleHttp\Client $grades, string $company, array $filters = []): Generator
{
$query = $filters + ['limit' => 100];
do {
$res = $grades->get("companies/$company/reviews", ['query' => $query]);
$page = json_decode((string) $res->getBody(), true);
yield from $page['data'];
$query['cursor'] = $page['meta']['next_cursor'];
} while ($page['meta']['has_more']);
}
foreach (all_reviews($grades, 'COMPANY_UUID', ['min_rating' => 4]) as $review) {
echo $review['uuid'], PHP_EOL;
}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 usesort=newestoroldestfor syncs. - To keep a copy in sync, store the newest
published_atyou have and ask withstart_datenext 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.