Skip to content

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.

Query parameters
ParameterTypeRequiredDescription
platformstringYesgooglebusiness
accountIdstringYesIntegration ID of the location from list_integrations
limitintegerNoMax reviews to return (1–50, default 25)
afterstringNoPagination cursor from a previous response

Exact source contract; origin modularized separately in code examples.

Response fields
FieldShape (from source example)Meaning
successboolean (example)Whether the request succeeded
reviewsarray (example)Reviews, newest first
reviews[].idstring (example)Review identifier
reviews[].ratinginteger 1–5 or null (source-stated)Star rating, or null if unspecified
reviews[].textstring (example)Review text
reviews[].reviewer.namestring (example)Reviewer name
reviews[].reviewer.photoUrlstring (example)Reviewer photo URL
reviews[].createdAtstring timestamp (example)Review creation time
reviews[].updatedAtnull in example; general semantics not defined in sourceReview update time as shown in example
reviews[].replyobject or null (source-stated)Current owner reply, or null until the business owner replies
averageRatingnumber (example)Aggregate average rating
totalReviewCountinteger (example)Aggregate total review count
nextCursorstring 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.

List Reviews request
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
List Reviews response
{
	"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"
}
Contract example 1
GET /v1/reviews
x-access-key: YOUR_ACCESS_KEY