Check report status

Overview

See whether a report is still generating or ready.

Poll this every few seconds after starting a report.

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

Returns the status.

Prerequisites

Base URL

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

Endpoint

POST /api/v1/account/insight-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

FieldTypeRequiredDescription
store_idintegerYesThe location the report is for. Must exist and be inside your account tree.
report_idintegerYesThe report's id (insight_report_id). Must exist and belong to store_id.

Request payload

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

Response body

The payload is inside data.

FieldTypeDescription
insight_report_idintegerThe report's id.
store_idintegerThe location.
review_site_idinteger or nullThe review site, or null for a combined report across all the location's review sites.
publisherstringThe review site's source, e.g. maps.google.com, or all for a combined report.
yearintegerThe report year.
monthinteger or nullThe report month, or null for a full-year report.
themestringThe report theme, e.g. home-services.
statusstringpending, queued, processing, complete or failed.
task_idstring or nullThe report generator's task id.
review_countinteger or nullHow many reviews the report analysed. null until it's complete.
result_summaryobject or nullThe report itself, once it's complete: hero (headline and verdict), meta, themes (each with its score, what customers love, friction points and actions), summary (rating and sentiment totals), appendix, business and actionPlan. null until then.
failure_reasonstring or nullWhy the report failed, when it did.
failure_detailsstring or nullMore detail on the failure, when there is any.
created_atstring or nullWhen the report was requested (ISO 8601).
completed_atstring or nullWhen the report finished (ISO 8601). null while it's running.

Response payload

{
  "data": {
    "insight_report_id": 284,
    "store_id": 3007,
    "review_site_id": 44,
    "publisher": "maps.google.com",
    "year": 2026,
    "month": 8,
    "theme": "home-services",
    "status": "complete",
    "task_id": "7cf307e7-ed49-4016-aeed-084f215bc211",
    "review_count": 12,
    "result_summary": {
      "hero": {
        "verdict": "Your Service Quality is the clear strength — customers repeatedly praise the location's accessibility and seamless connections across Sydney. Communication and Responsiveness lags behind that excellence (66.7% positive), so you should focus on making contact and information clearer and more consistent to avoid eroding the strong overall rating.",
        "heroTitle": "Acme Coffee: Exceptional service, tighten communications",
        "anchorQuote": "Awsome experience",
        "closingLine": "Prioritise making information about access, connections and expected contact/response channels clearer across your customer touchpoints to lift your Communication and Responsiveness performance."
      },
      "meta": {
        "mode": "single",
        "version": "1.1",
        "reportType": "home-services-insights"
      },
      "themes": [
        {
          "id": "service-quality",
          "name": "Service Quality",
          "loves": [
            {
              "text": "Customers praise your location for being very accessible and well connected to different parts of Sydney, including bus, train and Light Rail links.",
              "keyword": "Accessibility & connections"
            },
            {
              "text": "Customers describe the integration of new and older rail infrastructure as seamless and say the site works well as a central transport hub in the CBD.",
              "keyword": "Transport hub"
            }
          ],
          "status": "STRONG",
          "actions": [
            {
              "text": "Install clear wayfinding signage at all major entrances that highlights bus, train and Light Rail connections and walking routes to nearby attractions like Darling Harbour and Hyde Park."
            },
            {
              "text": "Publish a simple access map and step-by-step walking directions on your website and on-site screens so customers immediately see how to navigate connections."
            }
          ],
          "mentions": 10,
          "frictions": [],
          "sentimentScore": 100,
          "negativeMentions": 0,
          "positiveMentions": 10
        },
        {
          "id": "communication-and-responsiveness",
          "name": "Communication and Responsiveness",
          "loves": [
            {
              "text": "Customers appreciate that your location feels less crowded than other hubs, which they identify as a positive part of the experience.",
              "keyword": "Lower crowding"
            },
            {
              "text": "Customers value that the site is a short walk to major destinations such as Darling Harbour and Hyde Park.",
              "keyword": "Proximity to attractions"
            }
          ],
          "status": "GOOD",
          "actions": [
            {
              "text": "Define and publish a clear response protocol on your contact page and at customer touchpoints that states which channels you monitor and what customers can expect when they contact you."
            },
            {
              "text": "Train front-line staff to use a short script for common enquiries and to log unanswered queries so you can measure and improve response consistency."
            }
          ],
          "mentions": 3,
          "frictions": [],
          "sentimentScore": 66.7,
          "negativeMentions": 0,
          "positiveMentions": 2
        },
        {
          "id": "pricing-and-value",
          "name": "Pricing and Value",
          "loves": [],
          "status": "NO_DATA",
          "actions": [
            {
              "text": "Begin collecting targeted feedback about pricing and perceived value at checkout and via a short follow-up survey so you can build enough data to evaluate this KPI."
            }
          ],
          "mentions": 0,
          "frictions": [],
          "sentimentScore": 0,
          "negativeMentions": 0,
          "positiveMentions": 0
        },
        {
          "id": "professionalism-and-staff-behavior",
          "name": "Professionalism and Staff Behavior",
          "loves": [],
          "status": "NO_DATA",
          "actions": [
            {
              "text": "Add an optional one-question staff professionalism rating to post-visit surveys to capture impressions of staff behaviour and create a baseline for this metric."
            }
          ],
          "mentions": 0,
          "frictions": [],
          "sentimentScore": 0,
          "negativeMentions": 0,
          "positiveMentions": 0
        }
      ],
      "summary": {
        "positiveRate": 92.3,
        "ratingStatus": "STRONG",
        "totalReviews": 12,
        "averageRating": 4.4,
        "negativeReviews": 0,
        "positiveReviews": 10
      },
      "appendix": {
        "footnote": "Based on 12 Google Maps reviews from August 2026.",
        "liveRating": 4.21,
        "methodology": "We score your reviews against the service dimensions that matter most in your industry, so results stay comparable month to month. Findings, quotes, and actions come from what your customers actually wrote. Each score is the share of mentions that were positive. Where a dimension has too few mentions to score, we say so.",
        "reportPeriod": "August 2026",
        "reviewSource": "Google Maps",
        "reviewsToDate": 681,
        "analysisPeriod": "Aug 01, 2026 - Aug 31, 2026",
        "extendedWindow": false,
        "reviewsAnalysed": 12,
        "reviewsReceived": 38,
        "totalReviewsAnalyzed": 12,
        "reviewsWithCommentsToDate": 305
      },
      "business": {
        "name": "Acme Coffee",
        "address": "1 George St, Sydney, New South Wales 2000, Australia",
        "category": null,
        "reportPeriod": {
          "label": "August 2026"
        },
        "reviewSource": "Google Maps",
        "analysisPeriod": {
          "end": "2026-08-31",
          "start": "2026-08-01",
          "display": "Aug 01, 2026 - Aug 31, 2026"
        }
      },
      "actionPlan": {
        "monitoring": [
          {
            "title": "Protect Service Quality",
            "cadence": "MONTHLY",
            "description": "Continue to monitor customer comments about accessibility and transport connections so you maintain your high Service Quality performance."
          },
          {
            "title": "Monitor Communication Score",
            "cadence": "MONTHLY",
            "description": "Track the percentage positive and response-related comments to measure the impact of any changes you make to contact protocols."
          },
          {
            "title": "Pricing & Value data gap",
            "cadence": "MONTHLY",
            "description": "Not enough reviews mention pricing or value yet to draw a conclusion; collect targeted feedback to populate this metric."
          },
          {
            "title": "Staff behaviour data gap",
            "cadence": "MONTHLY",
            "description": "Not enough reviews mention professionalism or staff behaviour yet to draw a conclusion; add a brief staff-rating question to capture this."
          }
        ],
        "priorities": []
      }
    },
    "failure_reason": null,
    "failure_details": null,
    "created_at": "2026-09-28T14:47:44+00:00",
    "completed_at": "2026-09-28T14:49:29+00:00"
  }
}

Examples

Success payload

The report is ready: see Response payload.

Still generating:

{
  "data": {
    "insight_report_id": 284,
    "store_id": 3007,
    "review_site_id": 44,
    "publisher": "maps.google.com",
    "year": 2026,
    "month": 8,
    "theme": "home-services",
    "status": "queued",
    "task_id": "7cf307e7-ed49-4016-aeed-084f215bc211",
    "review_count": null,
    "result_summary": null,
    "failure_reason": null,
    "failure_details": null,
    "created_at": "2026-09-28T14:47:44+00:00",
    "completed_at": null
  }
}

The report failed:

{
  "data": {
    "insight_report_id": 285,
    "store_id": 3007,
    "review_site_id": null,
    "publisher": "all",
    "year": 2026,
    "month": 8,
    "theme": "business-services",
    "status": "failed",
    "task_id": null,
    "review_count": null,
    "result_summary": null,
    "failure_reason": null,
    "failure_details": null,
    "created_at": "2026-09-28T14:47:47+00:00",
    "completed_at": "2026-09-28T14:47:47+00:00"
  }
}

Error payload

404 Report not found for this location

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

422 report_id missing

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

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."
    ]
  }
}

429 Too many requests

{
  "message": "Too Many Attempts."
}
StatusMeaning
200The report's current status, with the report once it's complete.
401The token is missing, expired or invalid.
404The report doesn't belong to store_id.
422A field is missing or invalid, the location is outside your tree, or the report doesn't exist.
429More than 60 requests in a minute from this user.
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": 3007, "report_id": 284}'

Did this page help you?