> ## 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 a query's mentions > The same mentions as `GET /v1/mentions`, scoped to one Query and carrying its **bucket** verdict. Filter to a bucket with `bucket=`, using an id from `GET /v1/queries/{id}/buckets` or the literal `uncategorised`. Cursor-paged: pass the response `nextCursor` back unchanged. Its absence means the last page. 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. `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. `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/queries/{id}/results 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 - url: http://localhost:3000 description: Local 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/queries/{id}/results: get: tags: - Queries summary: List a query's mentions description: >- The same mentions as `GET /v1/mentions`, scoped to one Query and carrying its **bucket** verdict. Filter to a bucket with `bucket=`, using an id from `GET /v1/queries/{id}/buckets` or the literal `uncategorised`. Cursor-paged: pass the response `nextCursor` back unchanged. Its absence means the last page. 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. `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. `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: getV1QueriesByIdResults parameters: - in: path name: id schema: type: string format: uuid required: true - 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: 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: q schema: type: string minLength: 1 maxLength: 120 - in: query name: mode schema: type: string enum: - text - semantic - in: query name: bucket schema: anyOf: - type: string const: uncategorised - type: string format: uuid - 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: 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: Mentions content: application/json: schema: $ref: '#/components/schemas/QueryMentionsResponse' '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: 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: QueryMentionsResponse: type: object properties: since: type: string until: type: string query: $ref: '#/components/schemas/QueryHeader' enabledSources: type: array items: type: string enum: - x - reddit - youtube - tiktok - bluesky - hackernews - mastodon - lemmy - github - producthunt - stackoverflow - rss - ai_answers - vinted mentions: type: array items: $ref: '#/components/schemas/QueryMention' nextCursor: type: string required: - since - query - enabledSources - mentions QueryHeader: type: object properties: id: type: string name: type: string kind: type: string enum: - catalog - listening aiEnabled: type: boolean isActive: type: boolean required: - id - name - kind - aiEnabled - isActive QueryMention: allOf: - $ref: '#/components/schemas/Mention' properties: bucket: oneOf: - $ref: '#/components/schemas/MentionBucket' - type: 'null' required: - bucket 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' query: 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 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 - query - run - title - body - url - metaLabel - sentiment - intent - authorHandle - marks - agent - media - fields - duplicateOf - duplicateCount - seeded MentionBucket: type: object properties: bucketId: type: - string - 'null' rationale: type: string confidence: type: - number - 'null' movedByUser: type: boolean required: - bucketId - rationale - confidence - movedByUser 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. ````