Brand, creator and topic questions, answered in one call

Three reports#

Each is one call under https://api.onekey.dev/v1/reports/ that turns a subject into a structured answer. They are built from search legs, profile legs, per-user post feeds and the computed block, and they never estimate: every number is a platform field, a published formula, or a counted judgment that names its method.

Coverage and warnings are part of the answer#

Every report carries a coverage block: which platforms answered, which failed (with status and error type), and which fields were absent on every item. A platform that failed shows as null in per-platform counts, never as 0, so a platform having a bad hour does not read as "nobody mentioned this". Missing parts show up as lines in _warnings. A report whose legs all failed fails with the first leg's error and charges nothing.

Then there are the deliberate refusals:

See the cost before you run it#

dry_run=true works on every report. For the handle torvalds on GitHub and Bluesky, recorded on the dev API (shortened):

curl "https://api.onekey.dev/v1/reports/creator-vet?handle=torvalds&platforms=github,bluesky&dry_run=true" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": {
    "legs": [
      { "platform": "github", "endpoint": "github.profile", "params": { "username": "torvalds" }, "credits": 1.0, "worst_case_credits": 3.0 },
      { "platform": "bluesky", "endpoint": "bluesky.profile", "params": { "handle": "torvalds" }, "credits": 1.0, "worst_case_credits": 1.0 },
      { "platform": "bluesky", "endpoint": "bluesky.posts", "params": { "handle": "torvalds" }, "credits": 1.0, "worst_case_credits": 1.0 }
    ],
    "credits": { "legs_worst_case": 5.0, "legs_list_price": 3.0, "ai": null }
  },
  "metadata": { "recipe": "creator_vet", "dry_run": true, "legs": 3, "credits_charged": 0.0 }
}

Each platform with a feed costs a profile leg plus a feed leg. Name the platforms you need with platforms= rather than relying on the default pool. Cadence feeds exist for eight platforms only (Bluesky, DEV Community, Hacker News, Instagram, Lobsters, Reddit, Twitch, X); every other platform gives profile numbers and a null cadence with a warning. 17 platforms have a profile endpoint today.

What a report costs#

The total is the legs at their own prices and nothing else: no surcharge for the report. A worst-case check runs first, cache hits are free, failed legs are refunded, your key's credit limit applies, and it counts as one request against the rate limit. AI lines, when AI is enabled for your account, are metered per judged row on top; they cannot be priced beforehand and the pre-release test figures on the docs pages are not prices. An Idempotency-Key replays a report at 0 credits.

Limits, honestly#

• Each platform's search decides what counts as a mention. A report counts the first page of each platform's results, not everything ever written.
• Tag-style searches get one keyword, and inputs.adapted shows it.
• Top authors are ranked by engagement_rate where a divisor exists, and otherwise by raw interactions, saying which in ranked_by. Most search rows carry no divisor.
• Reports are JSON only, and a report is not yet something a monitor can watch.
• AI-derived counts will be plumbing checks until a production model is connected; do not draw conclusions from the pre-release figures.