---
title: "Story Count Statistics"
method: GET
path: "/v1/stories/stats"
tags: ["v1"]
---

# Story Count Statistics

`GET /v1/stories/stats`

Get statistics on story counts over time intervals. Supports filtering by various story attributes and grouping by different time intervals (hour, day, week, month).

## Query parameters

- `q` string
- `name` string
- `clusterId` string[]
- `excludeClusterId` string[]
- `sortBy` 'createdAt' | 'updatedAt' | 'relevance' | 'count' | 'totalCount'
- `page` integer
- `size` integer
- `from` string, date-time
- `to` string, date-time
- `initializedFrom` string, date-time
- `initializedTo` string, date-time
- `updatedFrom` string, date-time
- `updatedTo` string, date-time
- `topic` string[]
- `category` string[]
- `taxonomy` string[]
- `source` string[]
- `sourceGroup` string[]
- `minUniqueSources` integer
- `minSourceDiversity` number
- `personWikidataId` string[]
- `personName` string
- `companyId` string[]
- `companyName` string
- `companyDomain` string[]
- `companySymbol` string[]
- `country` string[]
- `state` string[]
- `city` string[]
- `area` string[]
- `minClusterSize` integer
- `maxClusterSize` integer
- `nameExists` boolean
- `positiveSentimentFrom` number, float
- `positiveSentimentTo` number, float
- `neutralSentimentFrom` number, float
- `neutralSentimentTo` number, float
- `negativeSentimentFrom` number, float
- `negativeSentimentTo` number, float
- `showStoryPageInfo` boolean
- `showNumResults` boolean
- `showDuplicates` boolean
- `showHighlighting` boolean
- `highlightFragmentSize` integer
- `highlightNumFragments` integer
- `highlightPreTag` string
- `highlightPostTag` string
- `highlightQ` string
- `expandArticles` boolean
- `splitBy` 'HOUR' | 'DAY' | 'WEEK' | 'MONTH' | 'NONE', required

## Response `200`

200 - Success

- StatResult
  - `status` integer, nullable
  - `results` object[], nullable

## Other responses

- `400` — 400 - Bad Request
- `401` — 401 - Invalid API Key
- `403` — 403 - Request Forbidden
- `429` — 429 - Too Many Requests
- `500` — 500 - Server Error

## Changes

- **2026-05-07** `2c55bf07003a` — 1 info
  - added the new optional `query` request parameter `minSourceDiversity`
- **2025-08-18** `a73a3b58ca66` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/goperigon/apis/perigon-api/changes/v1/stories/stats/get.md)

---

[API](https://skmtc.dev/goperigon/apis/perigon-api.md) · [All operations](https://skmtc.dev/goperigon/apis/perigon-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/goperigon/perigon-api/revisions/2c55bf07003a/schema)