Skip to main content

​
Base URL

Every endpoint on this page is called against that host, and the API playground sends there too.

​
Authentication

Send your API key in every request:
See Authentication for key management.

​
What this API is

A Query polls the live Sources 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. This API is both halves of getting that back:
  • Pull — GET /v1/mentions across the whole Account, or GET /v1/queries/{id}/results per Query.
  • Push — signed webhook events and delivery channels, unchanged. See Webhooks.
And the management around it: create, edit, pause and resume the Queries themselves, run AI passes over items you name, and read your credit balance.

​
Pagination

Every list read is cursor-based: the response carries an opaque nextCursor, which you pass back unchanged on the next request. Its absence means the last page. GET /v1/vinted/items/{id}/price-history is bounded by limit, from and to instead.

​
Filters

Every reading filter follows one rule: repeat a key to OR its values, combine keys to AND them. ?sentiment=negative&sentiment=question&source=reddit is “negative or a question, on Reddit”. A handle is the account name as the Source writes it — no leading @, no u/, and case is kept: alice, alice@mastodon.social, Some-Repo-Owner. author is a filter, not a search; use q for 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. Filtering on intent, sentiment or author reads the polled stream only: items kept from a one-off Explore run carry no reading and no author.

​
Windows

Reads over time take an ISO-8601 since. Leave it out and you get a default window — 24 hours for /v1/mentions, 30 days for a Query’s results — and the response echoes back the since it actually read, so you never have to guess which window you got.

​
occurredAt and publishedAt

A mention carries two dates, and since and until both read the first one. occurredAt is when Nephia collected it — the instant the tick that caught it ran. publishedAt is when the platform says it was published. A watch meeting a two-year-old thread on today’s page reports today for one and 2024 for the other. Windowing on collection is what makes a sync loop safe: pass the since a response echoed back and nothing you have already read can arrive behind you. Windowing on publication could not promise that — an old post caught tomorrow would land in a window you already closed. So filter with occurredAt, and group, chart or age with publishedAt. publishedAt is null where the source gives no real date: an AI answer has none, and a YouTube video found through search reports a relative age (“4 years ago”) rather than a timestamp. Fall back to occurredAt when you need a date on every row.

​
What costs credits

Reading your own mentions is free. Two things meter:
  • mode=semantic on /v1/mentions and /v1/queries/{id}/results — searching by meaning rather than by substring calls an embedding provider. Charged at the same rate, through the same ten-minute cache, as the dashboard: re-asking the same question inside the window costs nothing.
  • POST /v1/analyses — see AI.
Everything else on this surface is a read of data you already paid to collect. See Credits.

​
Casing

Request bodies are snake_case and responses are camelCase, with one deliberate exception: the bodies of POST /v1/queries and PATCH /v1/queries/{id} are camelCase, matching the Query object those endpoints return. A Query is the one object you round-trip — read it, change a field, send it back — and that only works if the two spellings agree.

​
Absent is not null

On PATCH /v1/queries/{id}, a key you do not send is left alone; a key sent as null clears it. The difference is load-bearing: a search whose terms, filters or market change is started over on a new child watch, whose first poll records what currently matches without emitting it. The mentions the previous watch caught stay on the query. A new interval or webhook applies to the running watch and starts nothing over. The response’s resetSearches names the searches that were started over.

​
Rate limits

Every /v1/* call counts against a per-Account, per-minute request quota set by your plan (60/min on Free, up to 1,200/min on Pro). Responses carry RateLimit and RateLimit-Policy headers (IETF draft-7); over the quota you get 429 with Retry-After. See Limits.

​
Sources

Each Source page describes its coverage — what a Query or a Watch on it captures, and what arrives in each event:
  • X — tweets matching a search query
  • Reddit — posts from search or a subreddit
  • Youtube — videos from a search or a channel
  • Bluesky — posts by term and/or author
  • Hacker News — stories and comments matching a term
  • RSS & News — any feed on the web, plus news by term
  • AI answers — what ChatGPT, Gemini and Perplexity say about a prompt
  • Vinted — listings matching search criteria, plus observed price history and market stats

​
Errors

See Errors for the { error, code? } envelope and status codes.