Generate last month's report

Overview

Generate a report covering the previous calendar month.

Use this on a schedule for a monthly digest.

You'll need the store_id. The report is the combined report across all the location's review sites, with the theme from the account's industry. If a report for last month already exists (and hasn't failed), it's returned unchanged (200, deduped: true) and nothing is counted; otherwise a new one is generated and counts against your allowance.

Returns a report id to poll with Check report status.

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

Endpoint

POST /api/v1/account/insight-report/generate

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

The other fields of Generate an insight report (review_site_id, year, month, theme, force) are checked if you send them, but not used: the period is always the previous calendar month.

Request payload

{
  "store_id": 3007
}

Response body

The payload is inside data. Status 202 when a new report is queued; 200 when last month's report already exists. The fields are the same as Generate an insight report.

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": null,
    "publisher": "all",
    "year": 2026,
    "month": 9,
    "theme": "business-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

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

Last month's report already exists (200):

{
  "data": {
    "insight_report_id": 286,
    "store_id": 3007,
    "review_site_id": null,
    "publisher": "all",
    "year": 2026,
    "month": 9,
    "theme": "business-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,
    "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 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 store_id missing

{
  "message": "The store id field is required.",
  "errors": {
    "store_id": [
      "The store id field is required."
    ]
  }
}

429 Too many requests

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

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/account/insight-report/generate" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"store_id": 3007}'