Annual volume + rating chart (account-only)

Overview

Returns the last 12 months (relative to date) of per-month data for an account or a single store. Each month carries review volume, average rating, cumulative overall rating, and response counts. This drives the annual volume + rating chart.

Prerequisites

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

Base URL

Endpoint

POST /api/v1/graph/annual-volume

Authentication

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

• Who can call it: Partner and Account tokens.

• Mounted under the top-level api. group, not a partner/* prefix.

• Every identifier param runs through an ownership check, which resolves the target to a company id and rejects anything outside the caller's tree.

• An account caller (bundle_id=3) passes its own account_id/store_id or its own client_account_id/client_location_id.

• A partner caller (bundle_id=1) may pass any account/store under its child tree. External client ids are resolved against the partner's full descendant set.

• account_id must reference a bundle_id=3 (account) company row.

Rate limit

• No rate limit.

Request body

• Body:

*At least one of account_id, store_id, client_location_id, client_account_id is required (required_without_all).

{
  "account_id": 1,
  "review_site_id": 44,
  "date": "2026-06-01"
}

Response

• data.status (string) — always "success".
• data[].month (string) — month label formatted F-Y, e.g. "June-2026".
• data[].reviews (int) — count of qualifying reviews in that month.
• data[].avg_rating (float) — average rate of that month's reviews (0 if none).
• data[].overall_rating (float) — cumulative average rate of all qualifying reviews up to and including the end of that month.
• data[].responses (int) — count of reviews in that month that have a recorded response.

200 Success · 200

{
  "data": {
    "status": "success",
    "data": [
      { "month": "July-2025", "reviews": 3, "avg_rating": 4.55, "overall_rating": 4.99, "responses": 3 },
      { "month": "August-2025", "reviews": 0, "avg_rating": 0, "overall_rating": 4.99, "responses": 0 }
    ]
  }
}

Errors

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/graph/annual-volume" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"account_id": 1, "review_site_id": 44, "date": "2026-06-01"}'