---
updatedAt: 2026-11-11T07:32:40.000Z
agentTools:
  projectIndex: https://docs.yotpo.com/llms.txt
---

# Reviews per product

Get detailed organic reviews per product including top opinions and best sentences found within the review content.

> 📘 Authentication and request format
>
> Authenticate with `Authorization: Bearer YOUR_ACCESS_TOKEN`. The Insights API does not accept the `X-Yotpo-Token` header.
>
> Send filters inside the `filter` object, pagination inside `paging` and sorting inside `sorting`. Fields sent at the top level of the body are ignored.
>
> To sort results, set `sorting.sorting_field` to `reviewed_at`. It is the only supported sort field; other values return `500`.

> 🚧 Note:
>
> This endpoint only returns organic reviews. Reviews from grouped products are not counted or returned in the response.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Reviews API (V1)",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.yotpo.com",
      "description": "Main API server for authenticated and write operations"
    }
  ],
  "components": {
    "securitySchemes": {
      "X-Yotpo-Token": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Yotpo-Token",
        "description": "Your Yotpo account access token. See [Yotpo Authentication](ref:yotpo-authentication) to learn how to generate your token."
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Your Yotpo access token sent as `Authorization: Bearer YOUR_ACCESS_TOKEN`. Used by the Insights API."
      }
    }
  },
  "security": [
    {
      "X-Yotpo-Token": []
    }
  ],
  "paths": {
    "/insights/v1/products/reviews": {
      "post": {
        "summary": "Reviews per product",
        "description": "Get detailed organic reviews per product including top opinions and best sentences found within the review content.\n\n> 📘 Authenticate with `Authorization: Bearer YOUR_ACCESS_TOKEN`. The `X-Yotpo-Token` header is not accepted by the Insights API. Flat (un-nested) filter fields are ignored, so always nest them under `filter`.",
        "operationId": "product-reviews",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "filter"
                ],
                "properties": {
                  "filter": {
                    "type": "object",
                    "required": [
                      "app_key",
                      "sentiment_filter"
                    ],
                    "description": "Filters for the request. `app_key` is required. You must also send at least one of `external_product_ids` or `product_collections`.",
                    "properties": {
                      "app_key": {
                        "type": "string",
                        "description": "Your store ID (app key)."
                      },
                      "date_range": {
                        "type": "object",
                        "description": "Date range of the reviews to analyze.",
                        "properties": {
                          "start_date": {
                            "type": "string",
                            "description": "Start of the range, ISO 8601 (e.g. `2024-01-01T00:00:00.000Z`).",
                            "format": "date-time"
                          },
                          "end_date": {
                            "type": "string",
                            "description": "End of the range, ISO 8601 (e.g. `2024-12-31T23:59:59.999Z`).",
                            "format": "date-time"
                          }
                        }
                      },
                      "location": {
                        "type": "object",
                        "description": "Reviewer location filter.",
                        "properties": {
                          "countries": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Two-letter reviewer country codes, e.g. `US`. [See list](https://github.com/pariz/gountries/tree/master/data/json/countries)",
                            "example": [
                              "US"
                            ]
                          },
                          "states": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Reviewer state codes, e.g. `CA`. [See list](https://github.com/YotpoLtd/country-states/blob/master/us.go)",
                            "example": [
                              "CA"
                            ]
                          }
                        }
                      },
                      "external_product_ids": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Product IDs (domain keys / SKUs) to include.",
                        "example": [
                          "2063374417974"
                        ]
                      },
                      "product_groups": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Product group names as defined in your Yotpo product catalog."
                      },
                      "product_collections": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Product collection names as defined in your Yotpo product catalog."
                      },
                      "minimum_score": {
                        "type": "integer",
                        "description": "Minimum star rating, 1–5.",
                        "minimum": 1,
                        "maximum": 5
                      },
                      "exclude_unpublished": {
                        "type": "boolean",
                        "description": "Set to `true` to leave unpublished reviews out of the results."
                      },
                      "sentiment_filter": {
                        "type": "object",
                        "description": "Sentiment filter.",
                        "required": [
                          "sentiment_field"
                        ],
                        "properties": {
                          "sentiment_type": {
                            "type": "string",
                            "description": "Sentiment to return. Case-sensitive.",
                            "enum": [
                              "POSITIVE",
                              "NEGATIVE",
                              "NEUTRAL"
                            ]
                          },
                          "sentiment_field": {
                            "type": "string",
                            "description": "Set to `review_sentiment`. Required."
                          }
                        }
                      }
                    }
                  },
                  "paging": {
                    "type": "object",
                    "description": "Pagination. If omitted, up to 25 results are returned.",
                    "properties": {
                      "page": {
                        "type": "integer",
                        "description": "Page number, starting from 0.",
                        "minimum": 0
                      },
                      "per_page": {
                        "type": "integer",
                        "description": "Results per page.",
                        "minimum": 1
                      }
                    }
                  },
                  "sorting": {
                    "type": "object",
                    "description": "Sorting options.",
                    "properties": {
                      "sorting_field": {
                        "type": "string",
                        "description": "Field to sort by. `reviewed_at` is the only supported value and is required when you send `sorting`; omit `sorting` to use the default order.",
                        "enum": [
                          "reviewed_at"
                        ]
                      },
                      "sorting_direction": {
                        "type": "string",
                        "description": "Sort direction. Case-sensitive. Does not apply to `yotpo_default_sorting`.",
                        "enum": [
                          "ASC",
                          "DESC"
                        ]
                      }
                    }
                  }
                }
              },
              "examples": {
                "Body": {
                  "value": {
                    "filter": {
                      "app_key": "YOUR_STORE_ID",
                      "date_range": {
                        "start_date": "2018-01-01T00:00:00.000Z",
                        "end_date": "2018-07-09T00:00:00.000Z"
                      },
                      "sentiment_filter": {
                        "sentiment_type": "POSITIVE",
                        "sentiment_field": "review_sentiment"
                      },
                      "location": {
                        "countries": [],
                        "states": []
                      },
                      "product_groups": [],
                      "product_collections": [],
                      "minimum_score": 3,
                      "exclude_unpublished": false,
                      "external_product_ids": [
                        "2063374417974"
                      ]
                    },
                    "sorting": {
                      "sorting_field": "reviewed_at",
                      "sorting_direction": "ASC"
                    },
                    "paging": {
                      "page": 0,
                      "per_page": 3
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"paging\": {\n    \"page\": 0,\n    \"page_count\": 43,\n    \"per_page\": 3,\n    \"total\": 129\n  },\n  \"reviews\": [\n    {\n      \"review_id\": 59353058,\n      \"email\": \"anne.taylor@example.com\",\n      \"title\": \"\",\n      \"content\": \"The size 8 (which was the exchange for the size 10) is a perfect fit. How can I return the size 10. Would you kindly provide an address?\",\n      \"reviewed_at\": 1526398665000,\n      \"score\": 5,\n      \"opinions\": [\n        {\n          \"opinion\": \"is a perfect fit\",\n          \"sentence\": \"the size 8 (which was the exchange for the size 10) is a perfect fit.\"\n        }\n      ]\n    },\n    {\n      \"review_id\": 54890171,\n      \"email\": \"dennis@example.com\",\n      \"title\": \"A disappointment\",\n      \"content\": \"Well the shirt is of great quality, wash is nicely, and is wrinkle free, I was disappointed in the fact that the shirt tail is too long. It’s the right size and fits me fine everywhere, but as I said it’s not as short as the ones shown with the models.\",\n      \"reviewed_at\": 1519763233000,\n      \"score\": 3,\n      \"opinions\": [\n        {\n          \"opinion\": \"right size\",\n          \"sentence\": \"it’s the right size and fits me fine everywhere, but as i said it’s not as short as the ones shown with the models.\"\n        }\n      ]\n    },\n    {\n      \"review_id\": 59357759,\n      \"email\": \"kathleenk12345@example.com\",\n      \"title\": \"A good experience.\",\n      \"content\": \"Great fresh color; good fabric weight for Spring/Summer. It&#x27;s always hard to gauge the right size on a first-time purchase, so had to exchange an XL for a L. Dealing with the return was very easy; got the new shirt in no time. A pleasure doing business here.\",\n      \"reviewed_at\": 1526409770000,\n      \"score\": 5,\n      \"opinions\": [\n        {\n          \"opinion\": \"right size on a first-time purchase\",\n          \"sentence\": \"it's always hard to gauge the right size on a first-time purchase, so had to exchange an xl for a l. dealing with the return was very easy; got the new shirt in no time.\"\n        }\n      ]\n    }\n  ]\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "paging": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer",
                          "example": 0,
                          "default": 0,
                          "description": "Page number, starting at 0."
                        },
                        "page_count": {
                          "type": "integer",
                          "example": 43,
                          "default": 0,
                          "description": "Number of pages. On the review endpoints this can be `0` even when reviews are returned, so don't rely on it to stop paging."
                        },
                        "per_page": {
                          "type": "integer",
                          "example": 3,
                          "default": 0,
                          "description": "Results per page."
                        },
                        "total": {
                          "type": "integer",
                          "example": 129,
                          "default": 0,
                          "description": "Total number of results. On the review endpoints this can be `0` even when reviews are returned, so don't rely on it to stop paging."
                        }
                      },
                      "description": "Paging details."
                    },
                    "reviews": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "review_id": {
                            "type": "integer",
                            "example": 59353058,
                            "default": 0,
                            "description": "Review ID."
                          },
                          "email": {
                            "type": "string",
                            "example": "anne.taylor@email.com",
                            "description": "Reviewer's email address."
                          },
                          "title": {
                            "type": "string",
                            "example": "",
                            "description": "Review title."
                          },
                          "content": {
                            "type": "string",
                            "example": "The size 8 (which was the exchange for the size 10) is a perfect fit. How can I return the size 10. Would you kindly provide an address?",
                            "description": "Review text."
                          },
                          "reviewed_at": {
                            "type": "integer",
                            "example": 1526398665000,
                            "default": 0,
                            "description": "When the review was written, as a Unix timestamp in milliseconds (for example `1734998400000`)."
                          },
                          "score": {
                            "type": "integer",
                            "example": 5,
                            "default": 0,
                            "description": "Star rating (1-5)."
                          },
                          "opinions": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "opinion": {
                                  "type": "string",
                                  "example": "is a perfect fit",
                                  "description": "The opinion, as extracted from the review text (lowercase)."
                                },
                                "sentence": {
                                  "type": "string",
                                  "example": "the size 8 (which was the exchange for the size 10) is a perfect fit.",
                                  "description": "The sentence the opinion was found in."
                                }
                              }
                            },
                            "description": "Opinions found in the review that match the filter."
                          }
                        }
                      },
                      "description": "Reviews that match the filter."
                    }
                  }
                }
              }
            },
            "headers": {
              "ratelimit-limit": {
                "description": "The maximum number of requests allowed in the current time window",
                "schema": {
                  "type": "integer"
                }
              },
              "ratelimit-remaining": {
                "description": "The number of requests remaining in the current time window",
                "schema": {
                  "type": "integer"
                }
              },
              "ratelimit-reset": {
                "description": "The time (in seconds) until the rate limit resets",
                "schema": {
                  "type": "integer"
                }
              },
              "x-ratelimit-limit-minute": {
                "description": "The maximum number of requests allowed per minute",
                "schema": {
                  "type": "integer"
                }
              },
              "x-ratelimit-remaining-minute": {
                "description": "The number of requests remaining in the current minute",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            },
            "headers": {
              "ratelimit-limit": {
                "description": "The maximum number of requests allowed in the current time window",
                "schema": {
                  "type": "integer"
                }
              },
              "ratelimit-remaining": {
                "description": "The number of requests remaining in the current time window",
                "schema": {
                  "type": "integer"
                }
              },
              "ratelimit-reset": {
                "description": "The time (in seconds) until the rate limit resets",
                "schema": {
                  "type": "integer"
                }
              },
              "x-ratelimit-limit-minute": {
                "description": "The maximum number of requests allowed per minute",
                "schema": {
                  "type": "integer"
                }
              },
              "x-ratelimit-remaining-minute": {
                "description": "The number of requests remaining in the current minute",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid bearer token. The body is the plain string `unauthorized`."
          }
        },
        "deprecated": false,
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    }
  },
  "x-readme": {
    "headers": [
      {
        "value": "application/json",
        "key": "Content-Type"
      }
    ],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```