> ## Documentation Index > Fetch the complete documentation index at: https://docs.nephia.cc/llms.txt > Use this file to discover all available pages before exploring further. # Count mentions > Counts your mentions instead of paging them: how many, when, where, by whom and on which terms, in one call. `group_by` takes one or two axes among `day`, `hour`, `source`, `sentiment`, `intent`, `author`, `term` and `query`, and `rows` holds one count per combination. A combination with nothing in it is absent: a quiet day is a missing row, not a zero. `total` counts every mention in the window, whatever `top` kept. The open axes (`author`, `term`, `query`) keep their `top` busiest values and set `truncated` when they cut. A mention caught by two terms counts under each, so term rows can add up to more than `total`, and one with no recorded term counts under null. With `sentiment` or `intent` as an axis, `unread` is how many mentions nothing has read yet. The window is on the **publication** date, as Insights counts, not on the collection date `GET /v1/mentions` filters on, and covers 90 days at most. These are the numbers Insights shows: every mention caught, including the ones a mute rule or a hide keeps off the page, so a count can be higher than the rows the same filter pages. Only polled mentions are counted, and `kind=runs` is refused. Free: does not charge credits. `query` takes a Query id from `GET /v1/queries` and reads that Query's mentions only, including what its searches caught before they last changed. `source`, `sentiment` and `intent` are repeatable filters — `?sentiment=negative&sentiment=question` returns both, and repeated values of one key are OR'd while different keys are AND'd. `unread` selects mentions nothing has classified yet. Filtering on `sentiment` or `intent` reads the polled stream only: kept Explore-run items carry no reading. `author` is repeatable too, and **exact** — the handle as the Source writes it, with no leading `@` and no `u/`. Use `q` to search text. A handle you have never seen returns an empty page rather than an error, and a mention with no author never matches: not every Source carries a byline, and none carried one before author extraction shipped for it. `engagement_min` keeps mentions with at least that many **interactions** — likes, replies, reposts, comments or score, per Source. It never counts views. Mentions with no counters at all are left out rather than read as zero: RSS items and AI answers report no audience, and mentions recorded before 2026-09-04 predate the field. Counters are captured when we collect an item and never refreshed, so the threshold reads against recent mentions. Like `sentiment` and `intent`, it reads the polled stream only. `engagement` is a **per-Source** rule: `:`, repeatable — `?engagement=x:likes>=100&engagement=reddit:score>50`. Metrics are `likes`, `replies`, `reposts`, `comments`, `score`, `views`, plus `total` for the interaction sum `engagement_min` reads (`engagement_min=10` is exactly `engagement=*:total>=10`). Operators are `>=`, `>`, `=`, `<`, `<=`; the number is a whole number and may be negative, since Reddit and Lemmy net downvotes out. **A Source no rule names passes** — `?engagement=x:likes>=100` narrows X and leaves Hacker News alone — a named rule overrides `*` for its own Source, and several rules on one Source are ANDed; use `source=` to ask for one Source. **A metric that was never counted satisfies nothing, `<` included**: RSS items and AI answers report no audience, YouTube reports no likes, and mentions recorded before 2026-09-04 predate the field, so `engagement=youtube:likes<10` returns none of them rather than all of them. Send `engagement` or `engagement_min`, never both. ## OpenAPI ````yaml /openapi.json get /v1/mentions/stats openapi: 3.1.0 info: title: Nephia API description: >- The brand-monitoring API. Create a **Query** and it polls the live Sources (X, Reddit, Youtube, TikTok, Bluesky, Hacker News, Mastodon, Lemmy, GitHub, Product Hunt, Stack Overflow, RSS, AI answers — and Vinted) on an interval, keeps what matches, reads each mention for sentiment and intent, sorts it into your buckets and answers your own agent step over it. Read the result back as **mentions** — `GET /v1/mentions` across the whole Account, or per Query — or have it pushed to you as signed webhook events and delivery channels. A search can carry several terms at once, OR'd into one upstream request at one tick's cost. Authenticate with an API key on your Account. Monitoring is sold as a subscription — queries, terms, freshness and AI — with credits as the meter underneath; credit packs are overflow and never change a limit. Reading your own mentions is free; the semantic search mode and the AI passes are what meter. Request quota is per Account (all API keys share one bucket), by Plan: Free 60/min, Solo 350/min, Growth 700/min, Pro 1200/min. version: 1.0.0 servers: - url: https://api.nephia.cc description: Production security: - ApiKeyAuth: [] tags: - name: Account description: Account balance - name: Mentions description: Everything your Queries caught, across every Source - name: Queries description: The saved searches that do the catching — read, create, edit, pause - name: AI description: Group, classify, agent and summarise passes over items you name - name: X watches description: X watches, events, and activity - name: Reddit watches description: Reddit watches, events, and activity - name: Youtube watches description: Youtube watches, events, and activity - name: TikTok watches description: TikTok watches, events, and activity - name: Bluesky watches description: Bluesky watches, events, and activity - name: Hacker News watches description: Hacker News watches, events, and activity - name: Mastodon watches description: Mastodon watches, events, and activity - name: Lemmy watches description: Lemmy watches, events, and activity - name: GitHub watches description: GitHub watches, events, and activity - name: Product Hunt watches description: Product Hunt watches, events, and activity - name: Stack Overflow watches description: Stack Overflow watches, events, and activity - name: RSS watches description: RSS watches, events, and activity - name: AI answers watches description: AI answers watches, runs, events, and activity - name: Vinted watches description: Vinted watches, events, and activity - name: Vinted analytics description: Observed price history and per-day market statistics paths: /v1/mentions/stats: get: tags: - Mentions summary: Count mentions description: >- Counts your mentions instead of paging them: how many, when, where, by whom and on which terms, in one call. `group_by` takes one or two axes among `day`, `hour`, `source`, `sentiment`, `intent`, `author`, `term` and `query`, and `rows` holds one count per combination. A combination with nothing in it is absent: a quiet day is a missing row, not a zero. `total` counts every mention in the window, whatever `top` kept. The open axes (`author`, `term`, `query`) keep their `top` busiest values and set `truncated` when they cut. A mention caught by two terms counts under each, so term rows can add up to more than `total`, and one with no recorded term counts under null. With `sentiment` or `intent` as an axis, `unread` is how many mentions nothing has read yet. The window is on the **publication** date, as Insights counts, not on the collection date `GET /v1/mentions` filters on, and covers 90 days at most. These are the numbers Insights shows: every mention caught, including the ones a mute rule or a hide keeps off the page, so a count can be higher than the rows the same filter pages. Only polled mentions are counted, and `kind=runs` is refused. Free: does not charge credits. `query` takes a Query id from `GET /v1/queries` and reads that Query's mentions only, including what its searches caught before they last changed. `source`, `sentiment` and `intent` are repeatable filters — `?sentiment=negative&sentiment=question` returns both, and repeated values of one key are OR'd while different keys are AND'd. `unread` selects mentions nothing has classified yet. Filtering on `sentiment` or `intent` reads the polled stream only: kept Explore-run items carry no reading. `author` is repeatable too, and **exact** — the handle as the Source writes it, with no leading `@` and no `u/`. Use `q` to search text. A handle you have never seen returns an empty page rather than an error, and a mention with no author never matches: not every Source carries a byline, and none carried one before author extraction shipped for it. `engagement_min` keeps mentions with at least that many **interactions** — likes, replies, reposts, comments or score, per Source. It never counts views. Mentions with no counters at all are left out rather than read as zero: RSS items and AI answers report no audience, and mentions recorded before 2026-09-04 predate the field. Counters are captured when we collect an item and never refreshed, so the threshold reads against recent mentions. Like `sentiment` and `intent`, it reads the polled stream only. `engagement` is a **per-Source** rule: `:`, repeatable — `?engagement=x:likes>=100&engagement=reddit:score>50`. Metrics are `likes`, `replies`, `reposts`, `comments`, `score`, `views`, plus `total` for the interaction sum `engagement_min` reads (`engagement_min=10` is exactly `engagement=*:total>=10`). Operators are `>=`, `>`, `=`, `<`, `<=`; the number is a whole number and may be negative, since Reddit and Lemmy net downvotes out. **A Source no rule names passes** — `?engagement=x:likes>=100` narrows X and leaves Hacker News alone — a named rule overrides `*` for its own Source, and several rules on one Source are ANDed; use `source=` to ask for one Source. **A metric that was never counted satisfies nothing, `<` included**: RSS items and AI answers report no audience, YouTube reports no likes, and mentions recorded before 2026-09-04 predate the field, so `engagement=youtube:likes<10` returns none of them rather than all of them. Send `engagement` or `engagement_min`, never both. operationId: getV1MentionsStats parameters: - in: query name: since schema: type: string format: date-time description: >- ISO-8601 lower bound, inclusive, on the date the mention was **published** (the collection date where the Source gives none), which is how Insights counts. Defaults to 7 days before `until`. - in: query name: until schema: type: string format: date-time description: >- ISO-8601 upper bound, inclusive, on the same date. Defaults to now. The window covers 90 days at most. - in: query name: group_by schema: type: string example: day,sentiment required: true description: >- One or two axes, comma-separated: day, hour, source, sentiment, intent, author, term, query. `day` and `hour` cannot be combined. - in: query name: top schema: type: integer minimum: 1 maximum: 50 description: >- How many values of an open axis (`author`, `term`, `query`) to keep, busiest first. Default 10, at most 50. - in: query name: kind schema: type: string enum: - polling - runs - in: query name: source schema: anyOf: - type: string enum: - x - reddit - youtube - tiktok - bluesky - hackernews - mastodon - lemmy - github - producthunt - stackoverflow - rss - ai_answers - vinted - type: array items: type: string enum: - x - reddit - youtube - tiktok - bluesky - hackernews - mastodon - lemmy - github - producthunt - stackoverflow - rss - ai_answers - vinted - in: query name: query schema: type: string format: uuid description: >- Only this Query's mentions, by id from `GET /v1/queries`, including what its searches caught before they last changed. An id that is not one of your Queries is a 404. - in: query name: intent schema: anyOf: - type: string enum: - purchase_intent - comparison - question - complaint - praise - other - unread - type: array items: type: string enum: - purchase_intent - comparison - question - complaint - praise - other - unread - in: query name: sentiment schema: anyOf: - type: string enum: - positive - neutral - negative - question - mixed - unread - type: array items: type: string enum: - positive - neutral - negative - question - mixed - unread - in: query name: author schema: anyOf: - type: string minLength: 1 maxLength: 200 - type: array items: type: string minLength: 1 maxLength: 200 - in: query name: engagement_min schema: type: integer minimum: 0 - in: query name: engagement schema: anyOf: - type: string minLength: 1 maxLength: 120 - type: array items: type: string minLength: 1 maxLength: 120 responses: '200': description: Counts content: application/json: schema: $ref: '#/components/schemas/MentionStatsResponse' '400': description: Invalid request content: application/json: schema: type: object properties: error: type: string code: type: string required: - error '404': description: Query not found content: application/json: schema: type: object properties: error: type: string code: type: string required: - error '429': description: >- Request quota exceeded. Retry after the `Retry-After` header (seconds). Response includes `RateLimit-*` headers (IETF draft-7). content: application/json: schema: type: object properties: error: type: string code: type: string required: - error example: error: Rate limit exceeded code: TOO_MANY_REQUESTS components: schemas: MentionStatsResponse: type: object properties: since: type: string until: type: string total: type: integer groupBy: type: array items: type: string enum: - day - hour - source - sentiment - intent - author - term - query rows: type: array items: $ref: '#/components/schemas/MentionStatsRow' unread: type: - integer - 'null' truncated: type: boolean required: - since - until - total - groupBy - rows - unread - truncated MentionStatsRow: type: object properties: day: type: string hour: type: string source: type: string enum: - x - reddit - youtube - tiktok - bluesky - hackernews - mastodon - lemmy - github - producthunt - stackoverflow - rss - ai_answers - vinted sentiment: type: - string - 'null' enum: - positive - neutral - negative - question - mixed - null intent: type: - string - 'null' enum: - purchase_intent - comparison - question - complaint - praise - other - null author: type: - string - 'null' term: type: - string - 'null' query: oneOf: - $ref: '#/components/schemas/MentionOrigin' - type: 'null' count: type: integer required: - count MentionOrigin: type: object properties: id: type: string name: type: string required: - id - name securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key created from the Nephia dashboard for your Account. ````