Generate an insight report

Overview

Start generating a report for a location over a period.

Use this when you want a fresh report.

You'll need the store_id. Optionally pick a review site, a period (year, and month for a single month) and a theme; with no year, the report covers the previous calendar month.

Returns a report id to poll with Check report status. Counts against your allowance. If a report for the same location, review site, period and theme already exists (and hasn't failed), that report is returned instead (200, deduped: true) and nothing is counted.

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

60 requests per minute, counted per user (the token’s user). See Rate limits.

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	`true` generates a new report even when one already exists for the same location, review site, period and theme. The new report counts against your allowance. Defaults to `false`.

Request payload

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

Response body

The payload is inside data. Status 202 when a new report is queued; 200 when an existing report is returned.

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": 284,
    "store_id": 3007,
    "review_site_id": 44,
    "publisher": "maps.google.com",
    "year": 2026,
    "month": 8,
    "theme": "home-services",
    "status": "queued",
    "task_id": "7cf307e7-ed49-4016-aeed-084f215bc211",
    "review_count": null,
    "result_summary": null,
    "failure_reason": null,
    "failure_details": null,
    "created_at": "2026-09-28T14:47:44+00:00",
    "completed_at": null,
    "remaining": 4,
    "overage": false,
    "usage_log_id": 5123
  }
}

Examples

Success payload

A new report queued (202): see Response payload.

A report for the same location, review site, period and theme already exists (200):

{
  "data": {
    "insight_report_id": 284,
    "store_id": 3007,
    "review_site_id": 44,
    "publisher": "maps.google.com",
    "year": 2026,
    "month": 8,
    "theme": "home-services",
    "status": "queued",
    "task_id": "7cf307e7-ed49-4016-aeed-084f215bc211",
    "review_count": null,
    "result_summary": null,
    "failure_reason": null,
    "failure_details": null,
    "created_at": "2026-09-28T14:47:44+00:00",
    "completed_at": null,
    "deduped": true
  }
}

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
    }
  }
}

429 Too many requests

{
  "message": "Too Many Attempts."
}

Status	Meaning
`200`	A report for the same location, review site, period and theme already exists; it's 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"}'