StatusSupportGet API keyDashboard
SchemasReviews

Schemas

Review

Use with AI

Buyers' public reviews of a product, with their star rating, text, photos, the variant bought and whether the purchase was verified.

Endpoints

2 endpoints return reviews on Amazon and TikTok Shop.

Schema

Every endpoint above returns an array of these objects as data, with a page object. The standard meta comes with every response.

platformstring

Platform ID (tiktokshop, …).

idstring

Platform-native review ID (string).

product_idstringnullable

ID of the product reviewed (equals product.id); null only for a review of something other than a product.

urlstring urinullable

Permalink, when the platform has one (TikTok Shop reviews have none).

ratingintegernullable

Star rating, 1 to 5; null when the review gives none.

titlestringnullable

The review's headline; null when it has none.

textstringnullable

Review body as plain text; null for a rating without text.

languagestringnullable

BCP-47 language of text, when the platform states it.

authorobject

The reviewing account, as the platform shows it (some platforms mask the name, e.g. G**a, and show no handle); every field null for an anonymous review.

ShowHide 6 child fields
idstringnullable

Platform-native account ID; null when only the handle is known.

usernamestringnullable

Handle without the @; null when the account has none.

display_namestringnullable

Display name shown on the profile.

urlstring urinullable

Canonical profile URL.

avatar_urlstring urinullable

Profile picture URL. Platform CDN URLs can expire within hours.

is_verifiedbooleannullable

Platform verification badge; null where the platform has no badge.

variant_idstringnullable

ID of the variant bought: one of the product's variants (TikTok Shop: product.platform_specific.tiktokshop.variants[].id).

variant_titlestringnullable

The variant bought, as the platform labels it (Color: Black).

mediaobject[]

Photos and videos attached to the review; [] when none.

ShowHide 8 child fields
typestring

Kind of file. New values may be added; treat unknown values as other.

One ofimagevideoaudiogif

urlstring urinullable

Direct file URL; null when the platform withholds it, or when the link would only work from SocialTap's network or with a login. Often signed and expiring: see expires_at.

expires_atstring date-timenullable

When url stops working, RFC 3339 UTC, read from the platform's signed URL; null when unknown or when it does not expire.

thumbnail_urlstring urinullable

Poster or preview image URL.

widthintegernullable

Width in pixels.

heightintegernullable

Height in pixels.

duration_msintegernullable

Duration in milliseconds (video and audio only).

alt_textstringnullable

Accessibility text provided by the author or platform.

country_codestringnullable

ISO 3166-1 alpha-2 country the review was written in, as the platform states it.

is_verified_purchasebooleannullable

The platform marks the reviewer as having bought the product through it.

is_incentivizedbooleannullable

The platform marks the review as written in exchange for a free product or reward.

published_atstring date-timenullable

When the review was posted, RFC 3339 UTC.

metricsobject

Counts at fetch time; null = hidden or not exposed, 0 = zero.

ShowHide 1 child field
helpful_countintegernullable

Readers who marked the review helpful; null when the platform shows no such count.

platform_specificobject

Fields only this platform has, under its ID (platform_specific.<platform>); each null when unknown.

approximate_fieldsstring[]

JSON paths of values rounded by the platform or parsed from display text (a date-only time). [] when all exact.

unknown_fieldsstring[]

JSON paths of lists whose [] means unknown rather than none (a source that cannot see a review's photos); null already means unknown for every other field. [] when every list is known.

Item errors

Besides the request-level errors every endpoint can return, review endpoints return:

CodeHTTPRetryMeaningWhat to do
not_found404NoThe item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why).Check the link or ID. Do not retry.
private_or_unavailable403NoThe item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code.Only public items can be fetched. Do not retry.

Last updated