Docs
API
Read your projects, each day's report and every match in it from your own scripts and agents. The API is read-only: filters are edited in the app.
Authentication
The account owner creates a token in Settings → API. It's shown once; send it as a bearer token. Tokens belong to your account and work while it has an active trial or subscription. Each token can make 60 requests a minute; above that you get 429 with a Retry-After header.
curl https://trykeywordsonar.com/api/v1/projects \ -H "Authorization: Bearer ks_…"
Endpoints
All are GET, under https://trykeywordsonar.com/api/v1.
| Path | Returns |
|---|---|
/projects | Your projects: id, name, address, whether the report is emailed. |
/projects/:id | A project's report schedule, its last 7 days (each complete, building, not_due or no_report, with its posts and at_cap), its filter lines (query, tags, a query_hash per line and a filter_set_hash for the project, and how Reddit covers each line), the state of each source in the last daily sweep, and Reddit keyword counts (including when a keyword hit its daily cap). |
/projects/:id/reports/:day | One day's report, the day as YYYY-MM-DD on your account's clock: its state and every post it holds, with the filters that matched each. 410 once the report is older than 7 days. |
/projects/:id/history | What your filters found in the week before you saved them (not in any report), newest first. Pages with cursor and limit (up to 200). |
Reading a day's report
A report covers one calendar day, midnight to midnight on your account's clock, and is built at your report hour the next day. Ask /projects/:id which days are complete, then read each one:
curl https://trykeywordsonar.com/api/v1/projects/p_…/reports/2026-10-12 \
-H "Authorization: Bearer ks_…"
{
"project_id": "p_…", "day": "2026-10-12", "state": "complete",
"posts": 23, "at_cap": false, "email_status": "sent",
"last_result_at": "2026-10-13T06:04:11.000Z",
"matches": [{
"item_id": 4211, "source": "reddit", "kind": "comment",
"community": "saas", "community_label": "r/SaaS",
"title": null, "parent_title": "What are you using for churn?",
"text": "We moved our cancellation flow to…", "text_truncated": false,
"url": "https://www.reddit.com/r/SaaS/comments/…",
"author": "maya_builds", "score": 12, "thread_key": "1x3…",
"published_at": "2026-10-12T14:01:40.000Z", "matched_at": "2026-10-13T06:03:52.000Z",
"filters": [{ "id": "w_…", "name": "\"cancellation flow\"", "tags": ["churn"] }],
"matched_terms": ["cancellation flow"]
}]
}Each post appears once, with every filter of the project that matched it. Texts longer than 5,000 characters are cut (text_truncated). X posts come as links only (text_withheld), as X's terms require, and a Bluesky post its author deleted has its text removed. Reports and their matches are kept for 7 days, so read them at least once a week.
Errors
Errors return { "error": { "status", "message" } }: 401 for a missing or revoked token, 403 when the account has no active plan, 404 for another account's project, 410 for a report older than 7 days and 429 above the rate limit.