Check report status

Overview

See whether a report is ready.

Poll after submitting.

You'll need the location (store_id) and the report id (report_id).

Returns the status and, when done, the report.

Prerequisites

A bearer token. See Authentication.
The location's id (store_id) and the report's id (report_id): competitive_report_id from Generate a competitive report or List past reports.

Base URL

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

Endpoint

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

Authentication

Partner or Account token

store_id must be inside your own account tree, and the report must belong to that location. A Partner token can check reports for any location under the partner; an Account token only for its own locations.
A location outside your tree is rejected with 422. A report that doesn't belong to store_id returns 404.

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 the report is for. Must exist and be inside your account tree.
`report_id`	integer	Yes	The report's id (`competitive_report_id`). Must exist and belong to `store_id`.

Request payload

{
  "store_id": 3007,
  "report_id": 48
}

Response body

The payload is inside data.

Field	Type	Description
`competitive_report_id`	integer	The report's id.
`store_id`	integer	The location.
`review_site_id`	integer	The review site.
`publisher`	string	The review site's source, e.g. `maps.google.com`.
`year`	integer	The report year.
`month`	integer or null	The report month, or `null` for a full-year report.
`theme`	string	The report theme.
`status`	string	As reported by the generator, e.g. `pending`, `queued`, `waiting_for_scrape`, `processing`, `succeeded`, `failed`.
`code`	integer or null	The generator's result code.
`reason_code`	string or null	The generator's reason code, set when a report fails.
`task_id`	string or null	The report generator's task id.
`competitors`	array of objects	The competitors compared: `id`, `name`, `profile_key`, and any address, `phone`, `description` and `tags` sent with them.
`competitor_count`	integer	How many competitors.
`review_count`	integer or null	How many reviews the report scored. `null` until it's complete.
`report_data`	object or null	The report itself, once it's complete. `null` until then.
`failure_reason`	string or null	Why the report failed, e.g. `scrape_failed`.
`failure_details`	string or null	More detail on the failure.
`created_at`	string or null	When the report was requested (ISO 8601).
`completed_at`	string or null	When the report finished (ISO 8601).

Response payload

{
  "data": {
    "competitive_report_id": 48,
    "store_id": 3007,
    "review_site_id": 44,
    "publisher": "maps.google.com",
    "year": 2026,
    "month": 8,
    "theme": "home-services",
    "status": "failed",
    "code": 400,
    "reason_code": null,
    "task_id": "605eefee-6253-4c66-a831-5945e17dce64",
    "competitors": [
      {
        "id": "comp_4b6b2b957d4856aa",
        "zip": "2000",
        "city": "Sydney",
        "name": "Circular Quay",
        "state": "NSW",
        "street": "Circular Quay",
        "country": "AU",
        "profile_key": "https://www.google.com/maps/place/Circular+Quay/@-33.8615,151.2108,17z"
      }
    ],
    "competitor_count": 1,
    "review_count": null,
    "report_data": null,
    "failure_reason": "scrape_failed",
    "failure_details": "The on-demand scrape for competitor 1 returned a terminal failure",
    "created_at": "2026-09-28T14:48:05+00:00",
    "completed_at": "2026-09-28T14:48:10+00:00"
  }
}

Examples

Success payload

The report failed (a competitor's profile couldn't be read): see Response payload.

Still generating:

{
  "data": {
    "competitive_report_id": 54,
    "store_id": 3007,
    "review_site_id": 44,
    "publisher": "maps.google.com",
    "year": 2026,
    "month": 9,
    "theme": "home-services",
    "status": "queued",
    "code": null,
    "reason_code": null,
    "task_id": "605eefee-6253-4c66-a831-5945e17dce64",
    "competitors": [
      {
        "id": "comp_4b6b2b957d4856aa",
        "name": "Pacific Breeze Heating & Air",
        "profile_key": "<competitor-profile-url>",
        "street": "123 Main St",
        "city": "San Diego",
        "state": "CA",
        "zip": "92101",
        "country": "US",
        "phone": "+15555550100"
      }
    ],
    "competitor_count": 1,
    "review_count": null,
    "report_data": null,
    "failure_reason": null,
    "failure_details": null,
    "created_at": "2026-10-01T09:00:00+00:00",
    "completed_at": null
  }
}

Error payload

404 Report not found for this location

{
  "message": "Competitive report not found for this store.",
  "status": "error",
  "errors": []
}

422 Report doesn't exist

{
  "message": "The selected report id is invalid.",
  "errors": {
    "report_id": [
      "The selected report id is invalid."
    ]
  }
}

422 report_id missing

{
  "message": "The report id field is required.",
  "errors": {
    "report_id": [
      "The report id field is required."
    ]
  }
}

429 Too many requests

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

Status	Meaning
`200`	The report's current status, with the report once it's complete.
`401`	The token is missing, expired or invalid.
`404`	The report doesn't belong to `store_id`.
`422`	A field is missing or invalid, the location is outside your tree, or the report doesn't exist.
`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/status" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"store_id": 3007, "report_id": 48}'