Skip to content

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.

Query parameters
ParameterRequiredTypeConstraintsDescription
platformRequiredstringValue in "googlebusiness"Platform the review lives on. Only googlebusiness today.
accountIdRequiredstring—Integration ID of the connected Google Business Profile location.
limitOptionalintegerDefault 25; range 1 <= value <= 50Page size; default 25, range 1-50.
afterOptionalstring—Pagination cursor from a prior response.

Exact captured query contract for GET /v1/reviews/

200 response fields
FieldRequiredTypeDescription
successRequiredboolean—
reviewsRequiredarray<object>Reviews, newest first.
reviews[].idRequiredstringReview identifier.
reviews[].ratingRequirednumber | nullStar rating 1-5, or null if unspecified.
reviews[].textRequiredstring | nullReview text.
reviews[].reviewerRequiredobjectReviewer object.
reviews[].reviewer.nameRequiredstring | nullReviewer name.
reviews[].reviewer.photoUrlRequiredstring | nullReviewer photo URL.
reviews[].createdAtRequiredstring | nullReview creation timestamp.
reviews[].updatedAtRequiredstring | nullReview update timestamp.
reviews[].replyRequiredobject | nullCurrent owner reply, or null if none exists.
reviews[].reply.textRequired when reply is presentstring | nullOwner reply text.
reviews[].reply.updatedAtRequired when reply is presentstring | nullOwner reply update timestamp.
averageRatingRequirednumber | nullAggregate average rating.
totalReviewCountRequirednumber | nullAggregate total review count.
nextCursorRequiredstring | nullCursor for the next page; pass as after.

Exact captured 200 response contract

Error responses
StatusContent typeBody shape
400application/json{ success: true, message: string }
401application/json{ success: true, message: string }
403application/json{ success: true, message: string }
404application/json{ success: true, message: string }
429application/json{ success: true, message: string }
502application/json{ success: true, message: string }

Exact captured error shape; no specific message values supplied

List Reviews API request
curl -X GET "{{API_BASE_URL}}/v1/reviews/?platform=googlebusiness&accountId=string" -H "x-access-key: <token>"
200 response example
{
  "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"
}
Error response example for 400, 401, 403, 404, 429 and 502
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
platform#1platformstring__0YesPlatform the review lives on. Only googlebusiness today.kind: schemaValueIn; value: "googlebusiness"
accountId#2accountIdstring__0YesIntegration ID of the connected Google Business Profile location.
limit#3limitinteger__0Nokind: schemaDefault; value: 25 | kind: schemaRange; value: 1 <= value <= 50
after#4afterstring__0NoPagination cursor from a prior response.
response#5responseobject__0
response#5response.successboolean__1Yes
response#5response.reviewsarray<object>__2Yes
response#5response.reviews[]object__3
response#5response.reviews[].idstring__4Yes
response#5response.reviews[].ratingnumber | null__5YesStar rating 1-5, or null if unspecified.
response#5response.reviews[].rating[variant1]number__5_type:numberStar rating 1-5, or null if unspecified.
response#5response.reviews[].rating[variant2]null__5_type:nullStar rating 1-5, or null if unspecified.
response#5response.reviews[].textstring | null__6Yes
response#5response.reviews[].text[variant1]string__6_type:string
response#5response.reviews[].text[variant2]null__6_type:null
response#5response.reviews[].reviewerobject__7Yes
response#5response.reviews[].reviewer.namestring | null__8Yes
response#5response.reviews[].reviewer.name[variant1]string__8_type:string
response#5response.reviews[].reviewer.name[variant2]null__8_type:null
response#5response.reviews[].reviewer.photoUrlstring | null__9Yes
response#5response.reviews[].reviewer.photoUrl[variant1]string__9_type:string
response#5response.reviews[].reviewer.photoUrl[variant2]null__9_type:null
response#5response.reviews[].createdAtstring | null__10Yes
response#5response.reviews[].createdAt[variant1]string__10_type:string
response#5response.reviews[].createdAt[variant2]null__10_type:null
response#5response.reviews[].updatedAtstring | null__11Yes
response#5response.reviews[].updatedAt[variant1]string__11_type:string
response#5response.reviews[].updatedAt[variant2]null__11_type:null
response#5response.reviews[].replyobject | null__12Yes
response#5response.reviews[].reply[variant1]object__12_extends:__13
response#5response.reviews[].reply[variant1].textstring | null__14Yes
response#5response.reviews[].reply[variant1].text[variant1]string__14_type:string
response#5response.reviews[].reply[variant1].text[variant2]null__14_type:null
response#5response.reviews[].reply[variant1].updatedAtstring | null__15Yes
response#5response.reviews[].reply[variant1].updatedAt[variant1]string__15_type:string
response#5response.reviews[].reply[variant1].updatedAt[variant2]null__15_type:null
response#5response.reviews[].reply[variant2]null__12_extends:__16
response#5response.averageRatingnumber | null__17Yes
response#5response.averageRating[variant1]number__17_type:number
response#5response.averageRating[variant2]null__17_type:null
response#5response.totalReviewCountnumber | null__18Yes
response#5response.totalReviewCount[variant1]number__18_type:number
response#5response.totalReviewCount[variant2]null__18_type:null
response#5response.nextCursorstring | null__19Yes
response#5response.nextCursor[variant1]string__19_type:string
response#5response.nextCursor[variant2]null__19_type:null
response#6responseobject__0
response#6response.successboolean__1Yes
response#6response.messagestring__2Yes