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 keyword 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 with GET /v1/mentions across the whole Account (?keyword=<id> narrows it to one), or GET /v1/keywords/{id}/results per keyword.
  • Count with GET /v1/mentions/stats: how many mentions per day, hour, Source, sentiment, intent, author, term or keyword, in one call and with the numbers Insights shows. Count there rather than by paging.
  • Push: signed webhook events and delivery channels. See Webhooks.
  • Replay with GET /v1/keywords/{id}/events: the same events, each in the body its webhook delivers, for code that has no endpoint or was down. When something looks wrong, GET /v1/keywords/{id}/activity lists every check and every delivery. Both are free.
  • Ask once with POST /v1/explore: one question across the Sources you name, without creating a keyword. It is priced first by POST /v1/explore/estimate, answers mentions, and is kept: re-read it free with GET /v1/mentions?run={id}. See Explore.
And the management around it: create, estimate, edit, pause and resume the keywords themselves, run AI passes over items you name, and read your credit balance.

​
Pagination

Mention reads are cursor-based: the response carries an opaque nextCursor, which you pass back unchanged on the next request. Its absence means the last page. A keyword’s /events, /activity and /ai-answers/runs are bounded by since and limit instead, and GET /v1/vinted/items/{id}/price-history by limit, from and to.

​
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 keyword’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 keyword 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. These meter:
  • mode=semantic on /v1/mentions and /v1/keywords/{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.
  • GET /v1/mentions/{id}/similar: the mentions closest in meaning to one you already have. Charged per mention asked about, through the same ten-minute cache; asking about a different mention charges again.
  • POST /v1/analyses — see AI.
  • POST /v1/explore: each search is charged at its Source’s explore rate when it runs, and a search that fails is not charged. POST /v1/explore/estimate gives the figure first, for free. See Explore.
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/keywords and PATCH /v1/keywords/{id} are camelCase, matching the keyword object those endpoints return. So are the bodies of POST /v1/explore and its estimate, which carry a keyword’s criteria. A keyword 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/keywords/{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, and its first poll records what currently matches without emitting it. The mentions caught before the change stay on the keyword. A new interval or webhook applies in place 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 keyword 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.