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.

PathReturns
/projectsYour projects: id, name, address, whether the report is emailed.
/projects/:idA 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/:dayOne 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/historyWhat 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.