Check status (poll until complete)

Overview

Polls the current status of a previously-queued competitive report, read straight from our database (the completed report lands via the COMPETITIVE_REPORT_RESULT webhook). Pure read — never calls ReviewData and never counts usage.

Prerequisites

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

Base URL

Endpoint

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

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, and report_id must be an existing competitive report.

• The service loads the row scoped to that store. A Partner can poll any store in its tree; an Account reaches only its own.

Rate limit

• No rate limit.

Request body

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

{
  "store_id": 42,
  "report_id": 1001
}

Response

• data.competitive_report_id (integer)
• data.store_id (integer)
• data.review_site_id (integer|null)
• data.publisher (string)
• data.year (integer)
• data.month (integer|null)
• data.theme (string)
• data.status (string) — e.g. queued, processing, succeeded, failed.
• data.task_id (string|null)
• data.competitors (array)
• data.competitor_count (integer)
• data.review_count (integer|null)
• data.report_data (object|null) — populated once the webhook completes the report.
• data.failure_reason (string|null)
• data.failure_details (mixed|null)
• data.completed_at (string|null, ISO 8601)

200 Pending (still processing) · 200

{
  "data": {
    "competitive_report_id": 1001,
    "store_id": 42,
    "status": "pending",
    "task_id": "9a893013-9aa8-4b8f-b3ff-6fd72f00a6ce",
    "report_data": null,
    "failure_reason": null,
    "completed_at": null
  }
}

404 Report not found for this store · 404

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

Errors

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": 42, "report_id": 1001}'