Check status (poll until complete)

Overview

Returns the current state of a previously queued insight report, scoped to its store. While a report is in flight and its status is stale, the service may poll ReviewData once per internal throttle window as a missed-webhook fallback. This does not limit or consume your requests. The completed result is delivered out of band by the INSIGHT_REPORT_RESULT webhook. Poll this endpoint while status is pending, queued, or processing until it becomes complete or failed.

Prerequisites

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

Base URL

EnvironmentURL
Productionhttps://production-api.shoutaboutus.com
Developmenthttps://development-api.shoutaboutus.com

Endpoint

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

Authentication

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

  • Who can call it: Partner and Account tokens.

  • store_id is validated by an ownership check (auth-company-tree walk), and the lookup further requires the report row's store_id to match.

  • A Partner can poll any report under a store in its sub-tree; an Account only reports for its own stores.

  • report_id alone is not enough — it is filtered by the scoped store_id.

Rate limit

  • Your requests to this endpoint are not rate-limited.
  • The internal throttle window mentioned above applies only to the service's ReviewData fallback poll.

Request body

  • Body (all top-level, JSON):
FieldTypeRequiredDescription
store_idintegeryesMust be an existing location inside your own account tree.
report_idintegeryesMust be an existing insight report. Must belong to the given store_id or the call 404s (insight_report_not_found).
{
  "store_id": 42,
  "report_id": 1001
}

Response

  • data.insight_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) — pending | queued | processing | complete | failed.
  • data.task_id (string|null) — RD task id.
  • data.review_count (integer|null)
  • data.result_summary (object|null) — populated by the webhook on completion.
  • data.failure_reason (string|null)
  • data.failure_details (object|null)
  • data.completed_at (string|null) — ISO-8601.

Returns 404 (insight_report_not_found) when the report does not exist for this store.

200 Success (report ready) · 200

{
  "data": {
    "insight_report_id": 4,
    "store_id": 10,
    "review_site_id": 44,
    "publisher": "maps.google.com",
    "year": 2026,
    "month": null,
    "theme": "home-services",
    "status": "success",
    "task_id": "9a893013-9aa8-4b8f-b3ff-6fd72f00a6ce",
    "review_count": 6,
    "result_summary": {
      "hero": {
        "verdict": "Customers recognise strong technical ability and reliable execution on delivered work, but equally report systemic failures in communication and delivery readiness that have led to serious dissatisfaction. Fixing transparency, single-point accountability and release-readiness will convert the existing strengths into consistent customer outcomes.",
        "heroTitle": "hipages 540362 (SAU178040716910) — Strong Delivery, Fragile Follow‑through",
        "anchorQuote": "reliable execution, timely delivery, and professional communication",
        "closingLine": "This quarter prioritise a single-point-of-contact + response SLA program and a mandatory production-readiness checklist to stop repeat communication and delivery failures."
      },
      "meta": {
        "mode": "single",
        "version": "1.0",
        "reportType": "general-insights"
      },
      "themes": [
        {
          "id": "customer-experience",
          "name": "Customer Experience",
          "loves": [
            {
              "text": "Felt like a true collaboration — the team was patient, collaborative, and willing to refine things.",
              "keyword": "Collaboration"
            }
          ],
          "quote": {
            "text": "felt like a true collaboration"
          },
          "status": "CRITICAL",
          "actions": [
            {
              "text": "Assign a named account owner to every client, require a 24-hour acknowledgement and a substantive update within 3 business days, and publish a live project timeline (visible to client) with change logs."
            }
          ],
          "mentions": 6,
          "frictions": [
            {
              "text": "Customers reported a lack of transparency and follow-up, saying communication is the most basic expectation and it was not met.",
              "keyword": "Transparency"
            }
          ],
          "sentimentScore": 50,
          "negativeMentions": 3,
          "positiveMentions": 3
        },
        {
          "id": "food-and-beverage",
          "name": "Food and Beverage",
          "loves": [],
          "quote": null,
          "status": "NO_DATA",
          "actions": [
            {
              "text": "Begin collecting Food & Beverage-specific feedback by enabling the category in post-service surveys and prompting clients for a short review when the category applies; this will create a baseline for future action."
            }
          ],
          "mentions": 0,
          "frictions": [],
          "sentimentScore": 0,
          "negativeMentions": 0,
          "positiveMentions": 0
        },
        {
          "id": "service-quality",
          "name": "Service Quality",
          "loves": [
            {
              "text": "Customers praise strong technical proficiency and the ability to deliver clean, user-friendly designs with thorough testing.",
              "keyword": "Technical expertise"
            }
          ],
          "quote": {
            "text": "team stayed responsive and solution-oriented"
          },
          "status": "CRITICAL",
          "actions": [
            {
              "text": "Introduce a mandatory production-readiness checklist and require end-to-end QA sign-off before handover, plus assign a single accountable technical lead for every project to prevent diffused responsibility."
            }
          ],
          "mentions": 6,
          "frictions": [
            {
              "text": "Critical features failed to work properly and multiple handovers between project managers meant no single team was accountable for a production-ready product.",
              "keyword": "Delivery failure"
            }
          ],
          "sentimentScore": 50,
          "negativeMentions": 3,
          "positiveMentions": 3
        },
        {
          "id": "wait-times",
          "name": "Wait Times",
          "loves": [
            {
              "text": "Some customers reported timely delivery and quick turnaround on updates.",
              "keyword": "Timeliness"
            }
          ],
          "quote": {
            "text": "timely delivery"
          },
          "status": "CRITICAL",
          "actions": [
            {
              "text": "Define and enforce SLAs for status updates (acknowledge within 24 hours, substantive update every 3 business days), implement automated milestone notifications, and run a weekly audit to surface stalled items."
            }
          ],
          "mentions": 4,
          "frictions": [
            {
              "text": "Other customers had to repeatedly reach out for updates and experienced no timely responses for weeks.",
              "keyword": "No follow-up"
            }
          ],
          "sentimentScore": 50,
          "negativeMentions": 2,
          "positiveMentions": 2
        }
      ],
      "summary": {
        "positiveRate": 50,
        "ratingStatus": "CRITICAL",
        "totalReviews": 6,
        "averageRating": 3.2,
        "negativeReviews": 3,
        "positiveReviews": 3
      },
      "appendix": {
        "generatedBy": "Shout About Us",
        "methodology": "This report analyses customer reviews using AI-powered sentiment analysis. Each review is categorised into themes, scored for positive or negative sentiment, and aggregated to produce the scores and insights above. Themes are generated from the actual review content, not from a fixed list.",
        "reviewSource": "Google Maps",
        "analysisPeriod": "Jan 01, 2026 - Dec 31, 2026",
        "totalReviewsAnalyzed": 6
      },
      "business": {
        "name": "hipages 540362 - site 2954679",
        "address": "Stub Address, Ashkāsham, Badakhshan 2000, Afghanistan",
        "category": null,
        "reportPeriod": {
          "end": "2026-12-31",
          "start": "2026-01-01",
          "display": "Jan 01, 2026 - Dec 31, 2026"
        },
        "reviewSource": "Google Maps"
      },
      "actionPlan": {
        "monitoring": [],
        "priorities": [
          {
            "title": "Fix client communication and ownership",
            "urgency": "IMMEDIATE",
            "description": "Assign a named account owner for all active projects, enforce a 24-hour acknowledgement and 3-business-day substantive update SLA, and log every client interaction so nothing falls through the cracks.",
            "relatedTheme": "Customer Experience"
          },
          {
            "title": "Enforce production-readiness",
            "urgency": "IMMEDIATE",
            "description": "Require a documented production-readiness checklist and mandatory end-to-end QA sign-off before any client handover to eliminate releases with broken critical features.",
            "relatedTheme": "Service Quality"
          },
          {
            "title": "Operationalise update SLAs",
            "urgency": "IMMEDIATE",
            "description": "Implement automated milestone notifications, weekly client status audits, and escalate any task with no update within 3 business days to a single accountable lead.",
            "relatedTheme": "Wait Times"
          }
        ]
      }
    },
    "failure_reason": null,
    "failure_details": null,
    "completed_at": null
  }
}

200 Pending (still processing) · 200

{
  "data": {
    "insight_report_id": 4,
    "store_id": 10,
    "review_site_id": 44,
    "publisher": "maps.google.com",
    "year": 2026,
    "month": null,
    "theme": "home-services",
    "status": "pending",
    "task_id": "9a893013-9aa8-4b8f-b3ff-6fd72f00a6ce",
    "review_count": null,
    "result_summary": null,
    "failure_reason": null,
    "failure_details": null,
    "completed_at": null
  }
}

404 Report not found for this store · 404

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

Errors

StatusMeaning
401The bearer token is missing, expired or invalid
404Report not found for this store
422The request failed validation — the response names the fields
500Unexpected server error

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/account/insight-report/status" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"store_id": 42, "report_id": 1001}'

Did this page help you?