> ## 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. # List mentions > Everything your keywords caught, newest first, across every Source and every keyword on the Account, annotated with the sentiment, intent and agent readings you have switched on, and filterable on both. Cursor-paged: pass the response `nextCursor` back unchanged. Its absence means the last page. To count mentions (per day, per Source, per sentiment, per author or term) call `GET /v1/mentions/stats` instead of paging: one free call, and the same numbers Insights shows. Free in the default `text` mode. Set `mode=semantic` to search by meaning instead of by substring. That path asks the embedding index and **charges** — at the same rate, through the same ten-minute cache, as the dashboard. Leave it out and the read is free. `keyword` takes a keyword id from `GET /v1/keywords` and reads that keyword's mentions only, including what its searches caught before they last changed. `run` takes the `run.id` `POST /v1/explore` answered and reads that kept run's mentions only, free: the way to come back to a run without paying for it again. `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. Bound the window at both ends with `since` and `until` — `?since=2026-08-03T00:00:00Z&until=2026-08-05T23:59:59Z` is those three days and nothing else. `until` is inclusive; absent, the window stays open at the top. ## OpenAPI ````yaml /openapi.json get /v1/mentions openapi: 3.1.0 info: title: Nephia API description: >- The brand-monitoring API. Create a **keyword** 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 keyword), 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 (keywords, 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 keywords caught, across every Source - name: Keywords description: >- What you monitor. A keyword carries its terms, its Sources and its settings. Read, create, edit and pause them here. - name: Explore description: >- One question asked of the Sources once, priced first, without creating a keyword - name: AI description: Group, classify, agent and summarise passes over items you name - name: Vinted analytics description: Observed price history and per-day market statistics paths: /v1/mentions: get: tags: - Mentions summary: List mentions description: >- Everything your keywords caught, newest first, across every Source and every keyword on the Account, annotated with the sentiment, intent and agent readings you have switched on, and filterable on both. Cursor-paged: pass the response `nextCursor` back unchanged. Its absence means the last page. To count mentions (per day, per Source, per sentiment, per author or term) call `GET /v1/mentions/stats` instead of paging: one free call, and the same numbers Insights shows. Free in the default `text` mode. Set `mode=semantic` to search by meaning instead of by substring. That path asks the embedding index and **charges** — at the same rate, through the same ten-minute cache, as the dashboard. Leave it out and the read is free. `keyword` takes a keyword id from `GET /v1/keywords` and reads that keyword's mentions only, including what its searches caught before they last changed. `run` takes the `run.id` `POST /v1/explore` answered and reads that kept run's mentions only, free: the way to come back to a run without paying for it again. `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. Bound the window at both ends with `since` and `until` — `?since=2026-08-03T00:00:00Z&until=2026-08-05T23:59:59Z` is those three days and nothing else. `until` is inclusive; absent, the window stays open at the top. operationId: getV1Mentions parameters: - in: query name: since schema: type: string format: date-time - in: query name: until schema: type: string format: date-time description: >- ISO-8601 upper bound on `occurredAt` — the date Nephia collected the mention, not the date it was published. Inclusive. Absent means the window is open at the top. With `since`, this is a closed interval — `?since=2026-08-03T00:00:00Z&until=2026-08-05T23:59:59Z` is those three days and nothing else. - in: query name: limit schema: type: integer minimum: 1 maximum: 100 - in: query name: cursor schema: type: string minLength: 1 - in: query name: type schema: type: string enum: - listing.created - listing.delisted - listing.price_changed - tweet.created - post.created - reddit_comment.created - video.created - bluesky_post.created - hn_item.created - article.created - answer.created - answer.changed - term.cited - term.uncited - status.created - lemmy_post.created - github_item.created - launch.created - stack_item.created - tiktok_video.created - in: query name: kind schema: type: string enum: - polling - runs - in: query name: run schema: type: string format: uuid - in: query name: q schema: type: string minLength: 1 maxLength: 120 - in: query name: mode schema: type: string enum: - text - semantic - 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: keyword schema: type: string format: uuid description: >- Only this keyword's mentions, by id from `GET /v1/keywords`, including what its searches caught before they last changed. An id that is not one of your keywords 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: relevance schema: anyOf: - type: string enum: - high - medium - low - unread - type: array items: type: string enum: - high - medium - low - 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 - in: query name: opportunity schema: type: string enum: - 'true' - 'false' example: 'true' description: >- `true` keeps only **opportunities**: mentions of a `topic` or `competitor` keyword that are highly relevant to it and whose author is someone to answer. On a keyword whose agent step has a boolean `problem_fit` field, that is `problem_fit: true` under the current step; on any other, an intent of `purchase_intent`, `comparison` or `question`. An `own` keyword has none. Free. responses: '200': description: Mentions content: application/json: schema: $ref: '#/components/schemas/MentionsResponse' '400': description: Invalid request content: application/json: schema: type: object properties: error: type: string code: type: string required: - error '402': description: Insufficient credits (semantic mode only) content: application/json: schema: type: object properties: error: type: string code: type: string required: - error '404': description: Keyword 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: MentionsResponse: type: object properties: since: type: string until: type: string mentions: type: array items: $ref: '#/components/schemas/Mention' nextCursor: type: string required: - since - mentions Mention: type: object properties: id: type: string source: type: string enum: - x - reddit - youtube - tiktok - bluesky - hackernews - mastodon - lemmy - github - producthunt - stackoverflow - rss - ai_answers - vinted type: type: string enum: - listing.created - listing.delisted - listing.price_changed - tweet.created - post.created - reddit_comment.created - video.created - bluesky_post.created - hn_item.created - article.created - answer.created - answer.changed - term.cited - term.uncited - status.created - lemmy_post.created - github_item.created - launch.created - stack_item.created - tiktok_video.created occurredAt: type: string publishedAt: type: - string - 'null' keyword: oneOf: - $ref: '#/components/schemas/MentionOrigin' - type: 'null' run: oneOf: - $ref: '#/components/schemas/MentionOrigin' - type: 'null' title: type: string body: type: string url: type: - string - 'null' metaLabel: type: string sentiment: type: - string - 'null' enum: - positive - neutral - negative - question - mixed - null intent: type: - string - 'null' enum: - purchase_intent - comparison - question - complaint - praise - other - null relevance: type: - string - 'null' enum: - high - medium - low - null relevanceReason: type: - string - 'null' matchedTerms: type: - array - 'null' items: type: string authorHandle: type: - string - 'null' marks: type: array items: type: string enum: - to_reply - starred - flagged - hidden agent: type: - object - 'null' additionalProperties: {} media: oneOf: - $ref: '#/components/schemas/MentionMedia' - type: 'null' fields: type: array items: type: object properties: label: type: string value: type: string required: - label - value duplicateOf: type: - string - 'null' duplicateCount: type: number seeded: type: boolean required: - id - source - type - occurredAt - publishedAt - keyword - run - title - body - url - metaLabel - sentiment - intent - relevance - relevanceReason - matchedTerms - authorHandle - marks - agent - media - fields - duplicateOf - duplicateCount - seeded MentionOrigin: type: object properties: id: type: string name: type: string required: - id - name MentionMedia: type: object properties: thumbnailUrl: type: - string - 'null' imageUrls: type: array items: type: string avatarUrl: type: - string - 'null' durationLabel: type: - string - 'null' required: - thumbnailUrl - imageUrls - avatarUrl - durationLabel securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key created from the Nephia dashboard for your Account. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.