Regenerate a report

Overview

Generate a report again, even when one already exists for the same location, review site, period and theme. The earlier report is kept; the new one becomes the latest.

Use this if the underlying reviews changed.

You'll need the store_id and the same review site, period and theme as the report you want to redo, with force set to true. This is the same endpoint as Generate an insight report.

Returns a new report id to poll with Check report status. Counts against your allowance.

Prerequisites

A bearer token. See Authentication.
The location's id (store_id). The location needs at least 10 reviews in the last 48 months, and at least one linked review site that reports can use.
Insight reports must be on the location's plan.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

POST /api/v1/account/insight-report

Authentication

Partner or Account token

store_id must be inside your own account tree. A Partner token can generate reports for any location under the partner; an Account token only for its own locations.
A location outside your tree is rejected with 422.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Field	Type	Required	Description
`store_id`	integer	Yes	The location to report on. Must exist and be inside your account tree.
`review_site_id`	integer	No	One review site to report on. Must exist and be linked to the location. Leave it out for a combined report across all the location's review sites (`publisher` is `all`).
`year`	integer	No	The report year, 2000 to 2100. Leave it out for a report on the previous calendar month (any `month` you send is then ignored).
`month`	integer	No	The report month, 1 to 12. Used only with `year`; with `year` and no `month`, the report covers the whole year.
`theme`	string	No	The report theme, at most 64 characters, e.g. `home-services`. Leave it out to use the account's industry, or `general` when no industry is set.
`force`	boolean	No	Send `true` to regenerate: a new report is generated even when one already exists for the same location, review site, period and theme, and it counts against your allowance. With `false` or left out, an existing report is returned instead (`200`, `deduped: true`).

Request payload

{
  "store_id": 3007,
  "review_site_id": 44,
  "year": 2026,
  "month": 8,
  "theme": "home-services",
  "force": true
}

Response body

The payload is inside data. With force: true, the status is 202 and a new report is queued.

Field	Type	Description
`insight_report_id`	integer	The report's id. Use it as `report_id` in Check report status.
`store_id`	integer	The location.
`review_site_id`	integer or null	The review site, or `null` for a combined report.
`publisher`	string	The review site's source, e.g. `maps.google.com`, or `all` for a combined report.
`year`	integer	The report year.
`month`	integer or null	The report month, or `null` for a full-year report.
`theme`	string	The report theme.
`status`	string	`pending`, `queued`, `processing`, `complete` or `failed`. A new report is usually `queued`.
`task_id`	string or null	The report generator's task id.
`review_count`	integer or null	How many reviews the report analysed. `null` until it's complete.
`result_summary`	object or null	The report itself. `null` until it's complete; see Check report status.
`failure_reason`	string or null	Why the report failed, when it did.
`failure_details`	string or null	More detail on the failure, when there is any.
`created_at`	string or null	When the report was requested (ISO 8601).
`completed_at`	string or null	When the report finished (ISO 8601). `null` while it's running.
`remaining`	integer or null	Only on `202`. Insight reports left on the location's allowance this period; `null` when there's no cap.
`overage`	boolean	Only on `202`. `true` when this report was billed as overage.
`usage_log_id`	integer	Only on `202`. The id of the usage record for this report.
`deduped`	boolean	Only on `200`. `true`: an existing report was returned and nothing was counted.

The response also carries the allowance in headers: X-Feature (insight_report), X-Feature-Limit, X-Feature-Used, X-Feature-Remaining (unlimited when there's no cap) and X-Feature-Hard-Stop (1 or 0).

Response payload

{
  "data": {
    "insight_report_id": 286,
    "store_id": 3007,
    "review_site_id": 44,
    "publisher": "maps.google.com",
    "year": 2026,
    "month": 8,
    "theme": "home-services",
    "status": "queued",
    "task_id": "3f2b8c1e-5d4a-4e7b-9c6f-2a1d0e8b7c5a",
    "review_count": null,
    "result_summary": null,
    "failure_reason": null,
    "failure_details": null,
    "created_at": "2026-10-01T09:00:00+00:00",
    "completed_at": null,
    "remaining": 4,
    "overage": false,
    "usage_log_id": 5123
  }
}

Examples

Success payload

See Response payload.

Error payload

403 Insight report allowance used up

{
  "message": "Limit reached for 'Insight Report': 5 of 5 units consumed this period.",
  "status": "error",
  "errors": {
    "remaining": 0
  }
}

422 Review site not linked to the location

{
  "message": "The selected review site is not linked to the given store.",
  "errors": {
    "review_site_id": [
      "The selected review site is not linked to the given store."
    ]
  }
}

422 Not enough reviews

{
  "message": "This location needs at least 10 reviews in the last 48 months before an insight report can be generated.",
  "errors": {
    "store_id": [
      "This location needs at least 10 reviews in the last 48 months before an insight report can be generated."
    ]
  }
}

422 Industry not supported yet

{
  "message": "Insight reports are not available for this account's industry yet. Please contact support.",
  "status": "error",
  "errors": {
    "reference": {
      "rd_request_id": null,
      "rd_error_code": null
    }
  }
}

422 Location outside your tree

{
  "message": "The selected store id does not belong to your company hierarchy.",
  "errors": {
    "store_id": [
      "The selected store id does not belong to your company hierarchy."
    ]
  }
}

502 Report provider error

{
  "message": "Insight report provider returned an error.",
  "status": "error",
  "errors": {
    "reference": {
      "rd_request_id": null,
      "rd_error_code": null
    }
  }
}

Status	Meaning
`200`	Only without `force: true`: an existing report is returned and nothing is counted.
`202`	A new report is queued. Poll Check report status.
`401`	The token is missing, expired or invalid.
`403`	The insight report allowance is used up on a hard-stop plan, insight reports aren't on the location's plan, or the location has no active plan.
`404`	The location's partner couldn't be found.
`422`	A field is missing or invalid; the location is outside your tree, has too few reviews, has no review site reports can use, or isn't set up with the report provider yet; the review site isn't linked to the location; or the account's industry isn't supported yet.
`429`	The report provider is rate-limiting requests. Try again later.
`500`	Unexpected server error.
`502`	The report provider returned an error or rejected the request.
`504`	The report provider is unreachable or timed out.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/account/insight-report" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"store_id": 3007, "review_site_id": 44, "year": 2026, "month": 8, "theme": "home-services", "force": true}'