AI insights report

Overview

Get the AI-insights report for a single store. It returns a live per-platform performance breakdown, computed from the latest 30 published reviews within a 6-month window. It also returns placeholder narrative fields (summary, key_insights) that are reserved for a future AI-generated summary and are not populated yet.

Prerequisites

• A bearer token. Callable with Partner and Account tokens.
• The required store_id query parameter (and the optional platform filter) — see Request 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.

• Access is not limited by a route prefix; the endpoint checks scope on each request.

• The store_id must be in the caller's accessible store set, otherwise the endpoint returns 403.

• For an account user, the reachable set is the stores under the account's child locations, plus any stores assigned directly to the user.

• The same endpoint serves both partner and account tokens — only which store_ids are reachable differs.

Rate limit

• No rate limit.

Query parameters

• Query: store_id (integer, required) — the target store's id; 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 — average of all review ratings), 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": {
      "hipages": {
        "count": 12,
        "avg_rating": 4.5,
        "positive_count": 9,
        "negative_count": 1
      }
    },
    "review_count_used": 28,
    "lookback_days": 154,
    "generated_at": "2026-06-10T09:14: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'