Submit insight report (generate)

Overview

Queue an async ReviewData insight report for one store + publisher. It counts 1 unit against the store's insight_report plan quota at submit time. Returns immediately with a task_id and status: queued. The completed report arrives later via the INSIGHT_REPORT_RESULT webhook (poll Check status (poll until complete) for the result). If a non-failed report already exists for the same (store, review site, period, theme), it comes back as-is without an RD call. Set force to bypass dedup and bill a fresh run.

Prerequisites

• A bearer token. Callable with Partner and Account tokens.

Base URL

Endpoint

POST /api/v1/account/insight-report

Authentication

• Requires a bearer token in the Authorization: Bearer <bearer-token> header.

• Who can call it: Partner and Account tokens.

• The target store is scoped by an ownership check on store_id, which walks the auth user's company tree.

• A Partner reaches every store in its partner sub-tree; an Account reaches only stores under its own company.

• The service resolves the parent partner to gate quota and pick the RD API key.

Rate limit

• Subject to rate limiting. Exceeding the rate limit returns a 429 response.

Request body

• Body (all top-level, JSON):

{
  "store_id": 42,
  "review_site_id": 7,
  "year": 2026,
  "month": 5,
  "theme": "home-services"
}

Response

• data.insight_report_id (integer) — our report record id.
• data.store_id (integer)
• data.review_site_id (integer|null)
• data.publisher (string) — publisher slug, or all when no review site given.
• data.year (integer)
• data.month (integer|null)
• data.theme (string)
• data.status (string) — queued (or RD-returned status) on a fresh submit; existing status when deduped.
• data.task_id (string|null) — RD task id.
• data.review_count (integer|null)
• data.result_summary (object|null)
• data.failure_reason (string|null)
• data.failure_details (object|null)
• data.completed_at (string|null) — ISO-8601.
• data.remaining (integer|null) — quota units remaining after this submit.
• data.overage (boolean) — true if billed as overage (soft-stop plan).
• data.usage_log_id (present only on fresh submit) / deduped: true (present only when an existing report is returned).

Quota-exceeded / feature-disabled returns 403 (insight_report_quota_exceeded); RD upstream issues return 502/504/429.

202 Queued · 202

{
  "data": {
    "insight_report_id": 4,
    "store_id": 10,
    "review_site_id": 44,
    "publisher": "maps.google.com",
    "year": 2026,
    "month": null,
    "theme": "home-services",
    "status": "queued",
    "task_id": "9a893013-9aa8-4b8f-b3ff-6fd72f00a6ce",
    "review_count": null,
    "result_summary": null,
    "failure_reason": null,
    "failure_details": null,
    "completed_at": null,
    "remaining": 4,
    "overage": false
  }
}

403 Quota exceeded / feature disabled · 403

{
  "status": "error",
  "message": "Insight report quota exceeded for this store.",
  "errors": []
}

422 Review site not linked to store · 422

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

Errors

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": 42, "review_site_id": 7, "year": 2026, "month": 5, "theme": "home-services"}'