List Reviews API
The List Reviews API returns Google Business Profile reviews for a connected location, ordered newest first. Each entry carries its star rating, reviewer details, written feedback, and any owner response already present. Listing reviews is free, and Google returns up to 50 reviews per page.
List Reviews API — GET {{API_BASE_URL}}/v1/reviews/
Use the List Reviews API to retrieve entries for a connected Google Business Profile location, sorted with the newest first. Every entry carries its star rating, reviewer details, written feedback, and any owner response already present. Supply the integration identifier through accountId. The operation requires the business.manage scope, which is requested at connect time. Google returns up to 50 reviews per page, so use nextCursor to page through results. Listing reviews is free.
Authorization
Authenticate every request with the accessKey in the x-access-key header. Send the token as the header value exactly as shown in the request example titled List Reviews API request. Do not send the token as a query parameter, because the captured contract places it in the header. The captured contract lists a 401 response shape but does not define its cause, so treat a 401 as a response to inspect rather than as a confirmed diagnosis.
Query Parameters
Build the query string with the required platform and accountId values, then add limit and after only when you need to control page size or continue from a prior page. Set platform to googlebusiness, the only supported value today, and set accountId to the integration ID of the connected Google Business Profile location. Omit limit to use the default of 25, or set it to an integer from 1 to 50. For the next page, copy the nextCursor value from the prior response into after. Before sending a request, check that platform is exactly googlebusiness, that accountId is present, and that limit, when present, is an integer within the allowed range. A missing or invalid value should be treated as a likely 400 failure, so fix the query string before retrying the same request.
200 application/json
A successful request returns a 200 response with success set to true, a reviews array, and the aggregate fields averageRating and totalReviewCount alongside nextCursor for pagination. Treat each review as a complete record: keep id for identification, rating for the star rating, text for the review body, reviewer for the reviewer name and photo URL, createdAt and updatedAt for timing, and reply for the current owner reply or null when no reply exists. Handle null values explicitly, because rating, text, reviewer fields, timestamps, reply fields, averageRating, totalReviewCount, and nextCursor can all be null under the captured types. Use averageRating and totalReviewCount as the aggregate values returned for the location, and pass nextCursor as after on the following request when it is present. The worked example is shown in the example titled 200 response example.
Error responses: 400, 401, 403, 404, 429, 502
Error responses for 400, 401, 403, 404, 429, and 502 share the same captured shape: success and message. The example titled Error response example for 400, 401, 403, 404, 429 and 502 shows that shape without assigning specific message values to any status. Check the HTTP status first, then read message for the returned explanation, and do not assume a more specific error code than the contract provides. The captured contract does not define status-specific causes or retry behaviour, so use the checks below only as generic triage: for a 400, recheck the query parameters against the field map; for a 401, recheck the x-access-key header; for a 403, recheck the connected location and granted scope; for a 404, recheck that accountId identifies the intended connected location; for a 429 or 502, do not treat the response as a successful review list and do not repeat the same call unchanged without reviewing the request.
Pagination with nextCursor
Pagination starts with a request that omits after, or with an explicit limit between 1 and 50. Reviews are returned newest first, with up to 50 per page. After each response, inspect nextCursor. If nextCursor is a string, send it back as after on the next request with the same platform and accountId. If nextCursor is null, there is no further cursor to follow from that response. Keep the same limit across pages when you need a stable page size, and do not construct a cursor yourself, because after must come from a prior response.
| Parameter | Required | Type | Constraints | Description |
|---|---|---|---|---|
| platform | Required | string | Value in "googlebusiness" | Platform the review lives on. Only googlebusiness today. |
| accountId | Required | string | — | Integration ID of the connected Google Business Profile location. |
| limit | Optional | integer | Default 25; range 1 <= value <= 50 | Page size; default 25, range 1-50. |
| after | Optional | string | — | Pagination cursor from a prior response. |
Exact captured query contract for GET /v1/reviews/
| Field | Required | Type | Description |
|---|---|---|---|
| success | Required | boolean | — |
| reviews | Required | array<object> | Reviews, newest first. |
| reviews[].id | Required | string | Review identifier. |
| reviews[].rating | Required | number | null | Star rating 1-5, or null if unspecified. |
| reviews[].text | Required | string | null | Review text. |
| reviews[].reviewer | Required | object | Reviewer object. |
| reviews[].reviewer.name | Required | string | null | Reviewer name. |
| reviews[].reviewer.photoUrl | Required | string | null | Reviewer photo URL. |
| reviews[].createdAt | Required | string | null | Review creation timestamp. |
| reviews[].updatedAt | Required | string | null | Review update timestamp. |
| reviews[].reply | Required | object | null | Current owner reply, or null if none exists. |
| reviews[].reply.text | Required when reply is present | string | null | Owner reply text. |
| reviews[].reply.updatedAt | Required when reply is present | string | null | Owner reply update timestamp. |
| averageRating | Required | number | null | Aggregate average rating. |
| totalReviewCount | Required | number | null | Aggregate total review count. |
| nextCursor | Required | string | null | Cursor for the next page; pass as after. |
Exact captured 200 response contract
| Status | Content type | Body shape |
|---|---|---|
| 400 | application/json | { success: true, message: string } |
| 401 | application/json | { success: true, message: string } |
| 403 | application/json | { success: true, message: string } |
| 404 | application/json | { success: true, message: string } |
| 429 | application/json | { success: true, message: string } |
| 502 | application/json | { success: true, message: string } |
Exact captured error shape; no specific message values supplied
curl -X GET "{{API_BASE_URL}}/v1/reviews/?platform=googlebusiness&accountId=string" -H "x-access-key: <token>"{
"success": true,
"reviews": [
{
"id": "string",
"rating": 0,
"text": "string",
"reviewer": {
"name": "string",
"photoUrl": "string"
},
"createdAt": "string",
"updatedAt": "string",
"reply": {
"text": "string",
"updatedAt": "string"
}
}
],
"averageRating": 0,
"totalReviewCount": 0,
"nextCursor": "string"
}{
"success": true,
"message": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| platform#1 | platform | string | __0 | Yes | Platform the review lives on. Only googlebusiness today. | kind: schemaValueIn; value: "googlebusiness" |
| accountId#2 | accountId | string | __0 | Yes | Integration ID of the connected Google Business Profile location. | |
| limit#3 | limit | integer | __0 | No | kind: schemaDefault; value: 25 | kind: schemaRange; value: 1 <= value <= 50 | |
| after#4 | after | string | __0 | No | Pagination cursor from a prior response. | |
| response#5 | response | object | __0 | |||
| response#5 | response.success | boolean | __1 | Yes | ||
| response#5 | response.reviews | array<object> | __2 | Yes | ||
| response#5 | response.reviews[] | object | __3 | |||
| response#5 | response.reviews[].id | string | __4 | Yes | ||
| response#5 | response.reviews[].rating | number | null | __5 | Yes | Star rating 1-5, or null if unspecified. | |
| response#5 | response.reviews[].rating[variant1] | number | __5_type:number | Star rating 1-5, or null if unspecified. | ||
| response#5 | response.reviews[].rating[variant2] | null | __5_type:null | Star rating 1-5, or null if unspecified. | ||
| response#5 | response.reviews[].text | string | null | __6 | Yes | ||
| response#5 | response.reviews[].text[variant1] | string | __6_type:string | |||
| response#5 | response.reviews[].text[variant2] | null | __6_type:null | |||
| response#5 | response.reviews[].reviewer | object | __7 | Yes | ||
| response#5 | response.reviews[].reviewer.name | string | null | __8 | Yes | ||
| response#5 | response.reviews[].reviewer.name[variant1] | string | __8_type:string | |||
| response#5 | response.reviews[].reviewer.name[variant2] | null | __8_type:null | |||
| response#5 | response.reviews[].reviewer.photoUrl | string | null | __9 | Yes | ||
| response#5 | response.reviews[].reviewer.photoUrl[variant1] | string | __9_type:string | |||
| response#5 | response.reviews[].reviewer.photoUrl[variant2] | null | __9_type:null | |||
| response#5 | response.reviews[].createdAt | string | null | __10 | Yes | ||
| response#5 | response.reviews[].createdAt[variant1] | string | __10_type:string | |||
| response#5 | response.reviews[].createdAt[variant2] | null | __10_type:null | |||
| response#5 | response.reviews[].updatedAt | string | null | __11 | Yes | ||
| response#5 | response.reviews[].updatedAt[variant1] | string | __11_type:string | |||
| response#5 | response.reviews[].updatedAt[variant2] | null | __11_type:null | |||
| response#5 | response.reviews[].reply | object | null | __12 | Yes | ||
| response#5 | response.reviews[].reply[variant1] | object | __12_extends:__13 | |||
| response#5 | response.reviews[].reply[variant1].text | string | null | __14 | Yes | ||
| response#5 | response.reviews[].reply[variant1].text[variant1] | string | __14_type:string | |||
| response#5 | response.reviews[].reply[variant1].text[variant2] | null | __14_type:null | |||
| response#5 | response.reviews[].reply[variant1].updatedAt | string | null | __15 | Yes | ||
| response#5 | response.reviews[].reply[variant1].updatedAt[variant1] | string | __15_type:string | |||
| response#5 | response.reviews[].reply[variant1].updatedAt[variant2] | null | __15_type:null | |||
| response#5 | response.reviews[].reply[variant2] | null | __12_extends:__16 | |||
| response#5 | response.averageRating | number | null | __17 | Yes | ||
| response#5 | response.averageRating[variant1] | number | __17_type:number | |||
| response#5 | response.averageRating[variant2] | null | __17_type:null | |||
| response#5 | response.totalReviewCount | number | null | __18 | Yes | ||
| response#5 | response.totalReviewCount[variant1] | number | __18_type:number | |||
| response#5 | response.totalReviewCount[variant2] | null | __18_type:null | |||
| response#5 | response.nextCursor | string | null | __19 | Yes | ||
| response#5 | response.nextCursor[variant1] | string | __19_type:string | |||
| response#5 | response.nextCursor[variant2] | null | __19_type:null | |||
| response#6 | response | object | __0 | |||
| response#6 | response.success | boolean | __1 | Yes | ||
| response#6 | response.message | string | __2 | Yes |