AI insights report

Overview

Get the AI-insights report envelope for a single store. It returns a live per-platform performance breakdown computed from the latest 30 non-suppressed, on-platform reviews within a 6-month window. It also returns stubbed narrative fields (summary, key_insights) reserved for a later AI-generation work-stream.

Prerequisites

• A bearer token. Callable with Partner and Account tokens.
• Values for the required query parameter store_id — see the table below.

Base URL

Endpoint

GET /api/v1/reports/insights

Authentication

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

• Who can call it: Partner and Account tokens.

• No prefix/partner-only access; scoping is in-controller.

• The store_id query value must be in the caller's accessible store set or the endpoint returns 403.

• As a partner-tree user, the reachable set is every store under the partner's company hierarchy (getStoreListByCompany).

• The same endpoint serves both roles — only which store_ids are reachable differs.

Rate limit

• No rate limit.

Query parameters

• Query: store_id (integer, required) — target store PK; must resolve inside the caller's access scope.
• Query: platform (string, optional) — filters reviews to a single review site's name (e.g. "hipages", "Google").

Response

• data.summary (string|null) — narrative summary; currently the stub string "AI insights pending generation." when reviews exist, otherwise null.
• data.key_insights (array) — AI narrative bullet objects; currently always [].
• data.category_performance (object) — keyed by platform name (reviewsite.name, or "Unknown"). Each value has count (int), avg_rating (float, rounded to 2dp — mean of all review ratings for the platform), positive_count (int, rate ≥ 4), negative_count (int, rate 1–2).
• data.review_count_used (int) — number of reviews aggregated (0–30).
• data.lookback_days (int) — days from oldest used review to now; defaults to 180 when no reviews found.
• data.generated_at (string) — ISO-8601 timestamp of generation.

200 Success · 200

{
  "data": {
    "summary": "AI insights pending generation.",
    "key_insights": [],
    "category_performance": {},
    "review_count_used": 28,
    "lookback_days": 154,
    "generated_at": "2026-05-29T14:30:00+00:00"
  }
}

403 Store out of scope · 403

{
  "status": "error",
  "message": "Store is outside your access scope.",
  "errors": []
}

Errors

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/reports/insights?store_id=123" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'