List stored competitive reports

Overview

List every competitive report stored for one store location, newest first (paginated), so the account can re-open a past report. Use each row's competitive_report_id with Check status (poll until complete) to fetch the full payload. DB-only read — never calls ReviewData and never counts usage. Optional status/publisher/theme/foreign_key filters narrow the list. The summary carries store-wide status counts and the total reviews scored for the page header.

Prerequisites

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

Base URL

Endpoint

POST /api/v1/account/competitive-report/list

Authentication

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

• Who can call it: Partner and Account tokens.

• The route sits directly under the authenticated group, not behind partner-only access.

• The store must sit inside your own account tree, keyed on store_id.

• Reports cover only that one store, so a Partner can list any store in its tree, an Account only its own.

Rate limit

• No rate limit.

Request body

• Body (success wrapped as { data. }, HTTP 200):

{
  "store_id": 42,
  "status": "succeeded",
  "publisher": "google",
  "theme": "home-services",
  "foreign_key": "competitor_1001",
  "per_page": 50,
  "page": 1
}

Response

• reports[] (array of objects):
• competitive_report_id (integer)
• foreign_key (string) — competitor_{id}.
• store_id (integer)
• business (string|null) — store saucode.
• business_name (string|null) — store name.
• review_site_id (integer|null)
• publisher (string)
• year (integer)
• month (integer|null)
• theme (string)
• status (string) — raw DB status.
• competitor_count (integer)
• competitors (array of string) — competitor names only.
• review_count (integer|null)
• owner_email (string|null) — requesting user email.
• requested_by_user_id (integer|null)
• created_at (string|null, ISO 8601)
• completed_at (string|null, ISO 8601)
• data.summary (object):
• status_counts (object) — map of raw status → count, across ALL the store's reports.
• reviews_scored (integer) — sum of review_count across all the store's reports.
• total (integer) — total report count for the store.
• data.data[].meta (object): current_page, last_page, per_page, total (all integers).

200 OK · 200

{
  "data": {
    "reports": [
      {
        "competitive_report_id": 1001,
        "store_id": 42,
        "publisher": "google",
        "year": 2026,
        "month": 5,
        "theme": "home-services",
        "status": "success",
        "competitor_count": 1,
        "completed_at": "2026-06-12T10:00:00Z"
      }
    ],
    "summary": {
      "status_counts": { "success": 1 },
      "reviews_scored": 128,
      "total": 1
    },
    "meta": {
      "current_page": 1,
      "last_page": 1,
      "per_page": 50,
      "total": 1
    }
  }
}

Errors

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/account/competitive-report/list" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"store_id": 42, "status": "succeeded", "publisher": "google", "theme": "home-services", "foreign_key": "competitor_1001", "per_page": 50, "page": 1}'