List Reviews API
The List Reviews API returns Google Business Profile reviews together with owner replies for one connected location, ordered with the most recent items first. A typical entry carries a star rating, the reviewer's display name, the written review, and whatever owner reply is currently present. Developers can use it to build a location review view, surface summary rating data, and walk through a large review set page by page.
Purpose and supported platform
Only one platform value is accepted here: googlebusiness. Under the hood, Google Business Profile reviews are obtained through the Business Profile API, with the business.manage scope requested when the location is connected. Google Business does not have a comments model; instead, each review can carry one owner reply. That distinction should shape your data model: represent an item as a review plus an optional single reply, rather than as a conversation thread. The source contract also states that listing reviews is free.
Request
Issue a GET request against the reviews path, supplying the x-access-key header. Two query parameters are mandatory, platform and accountId, and two are optional, limit and after. The accountId value is the Integration ID for the location, obtained from list_integrations, so look up the connected location first and pass that identifier rather than a display name or a native platform identifier. The source does not specify an error or status contract for an accountId that does not identify a connected location, so no specific failure behaviour is asserted here; validate the identifier on the client before calling.
Query parameters and pagination
Use limit to control page size, choosing a value between 1 and 50; when omitted, the default is 25. Google supplies at most 50 reviews in a single page, so values above 50 fall outside the documented range and should not be relied on. The after parameter carries a cursor obtained from an earlier response. To move forward, take the nextCursor from the current response and send it back as after on the following request. When nextCursor is null, there are no further pages, so pagination should stop rather than issuing another call with a null cursor.
Response fields and null semantics
A successful payload bundles a success flag, the reviews array, the aggregate fields averageRating and totalReviewCount, and nextCursor. Each review entry holds id, rating, text, a reviewer object with name and photoUrl, createdAt, updatedAt, and reply. Ratings run from 1 to 5, but rating can be null when no rating was given, so code must tolerate a missing numeric value. Reply stays null until the owner has responded. In the worked example, updatedAt is shown as null; the source does not define general null semantics for that field beyond the example. Use averageRating and totalReviewCount for summary displays, and keep following nextCursor until it becomes null.
Worked flow and failure checks
A straightforward flow starts with a first-page call using platform googlebusiness, the location's accountId, and a limit inside the 1 to 50 range, then saves the returned nextCursor. For each later page, repeat the same platform and accountId and set after to the saved cursor. When rendering, show a star rating only if rating is non-null, display the reviewer name and review text, and show owner replies only if reply is non-null. Once nextCursor is null, the complete set has been collected and paging ends. Never fabricate a cursor or reuse an earlier one after the final page.
| Parameter | Type | Required | Description |
|---|---|---|---|
| platform | string | Yes | googlebusiness |
| accountId | string | Yes | Integration ID of the location from list_integrations |
| limit | integer | No | Max reviews to return (1–50, default 25) |
| after | string | No | Pagination cursor from a previous response |
Exact source contract; origin modularized separately in code examples.
| Field | Shape (from source example) | Meaning |
|---|---|---|
| success | boolean (example) | Whether the request succeeded |
| reviews | array (example) | Reviews, newest first |
| reviews[].id | string (example) | Review identifier |
| reviews[].rating | integer 1–5 or null (source-stated) | Star rating, or null if unspecified |
| reviews[].text | string (example) | Review text |
| reviews[].reviewer.name | string (example) | Reviewer name |
| reviews[].reviewer.photoUrl | string (example) | Reviewer photo URL |
| reviews[].createdAt | string timestamp (example) | Review creation time |
| reviews[].updatedAt | null in example; general semantics not defined in source | Review update time as shown in example |
| reviews[].reply | object or null (source-stated) | Current owner reply, or null until the business owner replies |
| averageRating | number (example) | Aggregate average rating |
| totalReviewCount | integer (example) | Aggregate total review count |
| nextCursor | string or null (source-stated) | Pass as after for the next page; null means no more pages |
Shapes inferred from the source example where the source did not declare types; no additional fields invented.
GET {{API_BASE_URL}}/v1/reviews
x-access-key: YOUR_ACCESS_KEY
Query string example:
GET {{API_BASE_URL}}/v1/reviews?platform=googlebusiness&accountId=YOUR_ACCOUNT_ID&limit=25{
"success": true,
"reviews": [
{
"id": "AbFvOqlccRi2DR...",
"rating": 5,
"text": "An example comment.",
"reviewer": { "name": "Jane Doe", "photoUrl": "https://..." },
"createdAt": "2026-07-14T10:00:00.000Z",
"updatedAt": null,
"reply": null
}
],
"averageRating": 4.8,
"totalReviewCount": 325,
"nextCursor": "cursor_abc123"
}GET /v1/reviews
x-access-key: YOUR_ACCESS_KEY