List past reports

Overview

Get the competitive reports already generated for a location.

Use this to display history.

You'll need the store_id.

Returns the reports, newest first, with a summary across all the location's reports. Each row leaves out the report itself; open one with Check report status.

Prerequisites

A bearer token. See Authentication.
The location's id (store_id).

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

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

Authentication

Partner or Account token

store_id must be inside your own account tree. A Partner token can list 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

Field	Type	Required	Description
`store_id`	integer	Yes	The location. Must exist and be inside your account tree.
`status`	string	No	Filter by status, at most 32 characters. `queued` matches queued and pending reports; `in_progress` matches waiting_for_scrape, processing and running; `succeeded` matches succeeded, success, complete and completed; `failed` matches failed and error. Any other value matches that status exactly.
`publisher`	string	No	Filter by the review site's source, e.g. `maps.google.com`. At most 64 characters; exact match.
`theme`	string	No	Filter by theme, e.g. `home-services`. At most 64 characters; exact match.
`foreign_key`	string	No	Find one report by its `foreign_key` (`competitor_{id}`) or bare id. At most 64 characters. A value that isn't a number after the prefix matches nothing.
`per_page`	integer	No	Reports per page, 10 to 100 (values below 10 are raised to 10; above 100 returns `422`). Defaults to 50.
`page`	integer	No	The page, from 1. Defaults to 1.

Request payload

{
  "store_id": 3007,
  "status": "failed",
  "publisher": "maps.google.com",
  "theme": "home-services",
  "per_page": 50,
  "page": 1
}

Response body

The payload is inside data.

Field	Type	Description
`reports`	array	The reports on this page, newest first.
`reports[].competitive_report_id`	integer	The report's id. Use it as `report_id` in Check report status.
`reports[].foreign_key`	string	`competitor_{id}`.
`reports[].store_id`	integer	The location.
`reports[].business`	string or null	The location's external location id, e.g. `SAU17901602243007`.
`reports[].business_name`	string or null	The location's name.
`reports[].review_site_id`	integer or null	The review site.
`reports[].publisher`	string	The review site's source, e.g. `maps.google.com`.
`reports[].year`	integer	The report year.
`reports[].month`	integer or null	The report month, or `null` for a full-year report.
`reports[].theme`	string	The report theme.
`reports[].status`	string	The report's status, as stored.
`reports[].competitor_count`	integer	How many competitors.
`reports[].competitors`	array of strings	The competitors' names.
`reports[].review_count`	integer or null	How many reviews the report scored.
`reports[].owner_email`	string or null	Email of the user who requested the report.
`reports[].requested_by_user_id`	integer or null	Id of the user who requested the report.
`reports[].created_at`	string or null	When the report was requested (ISO 8601).
`reports[].completed_at`	string or null	When the report finished (ISO 8601).
`summary`	object	Totals across all the location's reports, not just this page.
`summary.status_counts`	object	How many reports have each status, keyed by status. An empty array `[]` when the location has no reports.
`summary.reviews_scored`	integer	Reviews scored across all the location's reports.
`summary.total`	integer	How many reports the location has.
`meta`	object	Paging: `current_page`, `last_page`, `per_page` and `total` (reports matching the filters).

Response payload

{
  "data": {
    "reports": [
      {
        "competitive_report_id": 48,
        "foreign_key": "competitor_48",
        "store_id": 3007,
        "business": "SAU17901602243007",
        "business_name": "Acme Coffee",
        "review_site_id": 44,
        "publisher": "maps.google.com",
        "year": 2026,
        "month": 8,
        "theme": "home-services",
        "status": "failed",
        "competitor_count": 1,
        "competitors": [
          "Circular Quay"
        ],
        "review_count": null,
        "owner_email": "[email protected]",
        "requested_by_user_id": 3011,
        "created_at": "2026-09-28T14:48:05+00:00",
        "completed_at": "2026-09-28T14:48:10+00:00"
      }
    ],
    "summary": {
      "status_counts": {
        "failed": 4
      },
      "reviews_scored": 0,
      "total": 4
    },
    "meta": {
      "current_page": 1,
      "last_page": 1,
      "per_page": 50,
      "total": 1
    }
  }
}

Examples

Success payload

See Response payload.

The location has no reports:

{
  "data": {
    "reports": [],
    "summary": {
      "status_counts": [],
      "reviews_scored": 0,
      "total": 0
    },
    "meta": {
      "current_page": 1,
      "last_page": 1,
      "per_page": 50,
      "total": 0
    }
  }
}

Error payload

422 Location outside your tree

{
  "message": "The selected store id does not belong to your company hierarchy.",
  "errors": {
    "store_id": [
      "The selected store id does not belong to your company hierarchy."
    ]
  }
}

422 per_page above 100

{
  "message": "The per page field must not be greater than 100.",
  "errors": {
    "per_page": [
      "The per page field must not be greater than 100."
    ]
  }
}

429 Too many requests

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

Status	Meaning
`200`	The location's reports, or an empty list.
`401`	The token is missing, expired or invalid.
`422`	A field is invalid, the location is outside your tree, or `per_page` is above 100.
`429`	More than 60 requests in a minute from this user.
`500`	Unexpected server error.

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": 3007, "status": "failed", "publisher": "maps.google.com", "theme": "home-services", "per_page": 50, "page": 1}'