Review Statistics

GET/api/v1/reviews/stats

Retrieve aggregate review statistics for your organization, including total review count, average rating, sentiment score, platform breakdown, and rating distribution.

Authentication

Bearer API Key — requires a Growth plan or higher.


curl "https://app.prooflio.io/api/v1/reviews/stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK


{
  "data": {
    "totalReviews": 142,
    "averageRating": 4.37,
    "averageSentiment": 0.71,
    "last30Days": 23,
    "last7Days": 8,
    "platforms": [
      { "platform": "GOOGLE", "count": 87, "averageRating": 4.5 },
      { "platform": "YELP", "count": 34, "averageRating": 4.1 },
      { "platform": "TRUSTPILOT", "count": 21, "averageRating": 4.3 }
    ],
    "ratingDistribution": [
      { "rating": 1, "count": 3 },
      { "rating": 2, "count": 5 },
      { "rating": 3, "count": 12 },
      { "rating": 4, "count": 45 },
      { "rating": 5, "count": 77 }
    ]
  }
}

Response Fields

Field	Type	Description
`totalReviews`	`number`	Total number of reviews across all platforms.
`averageRating`	`number \| null`	Overall average star rating (1–5).
`averageSentiment`	`number \| null`	Overall average AI sentiment score (0–1).
`last30Days`	`number`	Number of new reviews received in the past 30 days.
`last7Days`	`number`	Number of new reviews received in the past 7 days.
`platforms`	`array`	Breakdown by platform with count and average rating.
`ratingDistribution`	`array`	Count of reviews per star rating (1–5).

Platform Object

Field	Type	Description
`platform`	`string`	Platform name (e.g., `GOOGLE`, `YELP`).
`count`	`number`	Number of reviews from this platform.
`averageRating`	`number \| null`	Average rating for this platform.

Rating Distribution Object

Field	Type	Description
`rating`	`number \| null`	Star rating value (1–5).
`count`	`number`	Number of reviews with this rating.

Error Responses

Status	Description
`401 Unauthorized`	Missing or invalid API key.
`403 Forbidden`	Plan does not include API access.
`429 Too Many Requests`	Rate limit exceeded.

Usage Example


const response = await fetch('https://app.prooflio.io/api/v1/reviews/stats', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
});
const { data } = await response.json();
 
console.log(`Total reviews: ${data.totalReviews}`);
console.log(`Average rating: ${data.averageRating}★`);
console.log(`Avg sentiment: ${(data.averageSentiment * 100).toFixed(0)}% positive`);
console.log(`New this week: ${data.last7Days}`);
 
// Find your top platform
const topPlatform = data.platforms.sort((a, b) => b.count - a.count)[0];
console.log(`Top platform: ${topPlatform.platform} (${topPlatform.count} reviews)`);