Labels

include=labels and label= add small, structured judgments to every row a list endpoint returns: is this comment a question, is it a complaint, how positive is it, is the person asking to buy. You keep the endpoint's normal answer and get the judgments next to each row, in computed.labels.

Labels are signals, not verdicts. Each one is a level or a probability with a score, and you pick your own cut-off. Nothing else in https://api.onekey.dev is produced by a language model; this feature, relevance and themes are the only places one is involved, and the response says which method produced them.

When to use it#

• You pull the comments or replies under a post and want to find the questions, the complaints and the buying intent without reading them all.
• You want a sentiment number per row to sort or chart, and you are happy to choose the threshold yourself.
• You can live with a judgment being missing on a row: a row that could not be judged says so with null and is never guessed.

Labels are extra work on top of the endpoint, so they are metered separately. See AI pricing.

The request#

Add include=labels to any endpoint that accepts it. This judges every comment under a Hacker News story with that endpoint's default presets:

curl "https://api.onekey.dev/v1/hackernews/item_comments?id=8863&include=labels" \
  -H "x-api-key: YOUR_API_KEY"

To choose the presets yourself, name them with label=. It implies include=labels, and fewer presets cost less:

curl "https://api.onekey.dev/v1/hackernews/item_comments?id=8863&label=question,complaint" \
  -H "x-api-key: YOUR_API_KEY"

These combine with the other enrichment parameters on the same call: relevance= and themes=.

The presets#

p and confidence are numbers from 0 to 1. There is never a bare is_complaint: true: you decide where the line is.

Defaults by row kind#

Without label=, the presets depend on what a row is:

Which endpoints accept it#

31 list endpoints on 11 platforms accept enrichment today, plus multi-platform search (per platform) and batch items, which take the same parameters as a single call. The table is generated from each endpoint's own declaration, so it is always current; features.ai in GET /v1/platforms and x-ai in /openapi.json mark the same endpoints. The judged text is the field named in the third column: for a search result that is the title, for a post the title and body together.

Any enrichment parameter on another endpoint is a free 422 INVALID_PARAMS, and so is one on /v1/creator/card. The last column says whether the endpoint is a search, where relevance= is also allowed.

The response#

Each row gets computed.labels, and one labels summary block sits at the top level next to data. This is a recorded call on the pre-release test provider (rows shortened; methodology_version carries the test provider's method id, which marks that provider, see below):

{
  "success": true,
  "data": [
    {
      "content": { "id": "8869", "text": "This has great potential! Only suggestion I would have is go slower on the demo…" },
      "author": { "username": "…" },
      "computed": {
        "labels": {
          "complaint": { "p": 0.05 },
          "issue": { "topic": "usability", "confidence": 0.5 },
          "question": { "p": 0.05 },
          "sentiment": { "level": 4, "score_0_1": 0.7, "confidence": 0.95 }
        }
      }
    }
  ],
  "labels": {
    "presets": ["complaint", "issue", "question", "sentiment"],
    "mode": "sync",
    "status": "complete",
    "rows": 32,
    "labelled": 32,
    "cached": 0,
    "skipped": 0,
    "unjudged": 0,
    "pending": 0,
    "dropped": 0,
    "extra_credits": 60.225,
    "methodology_version": "fake/1"
  },
  "metadata": { "platform": "hackernews", "endpoint": "item_comments", "cached": false, "credits_charged": 65.225, "extra_credits": 60.225, "…": "…" },
  "error": null
}

metadata.extra_credits is the sum of every enrichment step in the call, and metadata.credits_charged already includes it.

How to read it honestly#

• Signals, not verdicts. A question.p of 0.7 is a probability from a model, not a fact about the comment. Choose the cut-off that fits your use, and spot-check rows near it.
• null means not judged, never "no". A skipped row has computed.labels: null. A row that had text but was not judged has {preset: null} for each preset. Treat both as unknown, not as a negative. Nothing is guessed to fill a gap.
• Count what was judged. rows, labelled, skipped and unjudged always add up the story. If labelled is smaller than rows, say so in whatever you build on top.
• Same text, same judgment. Identical texts (ignoring case and extra whitespace) are judged once and share the result. Texts longer than 2,000 characters are clipped before judging.
• methodology_version names the method. It is on every enrichment block. The value in the examples on these pages is the test provider's method id, the pre-release test provider: a deterministic keyword heuristic that exists so the feature can be built and tested end to end. It is not a measure of quality, and it is wrong on sarcasm, negation and non-English text. The value will change when a production method is in use, and judgments made under one version are never served as another.
• Limits per request. At most 200 rows of one request are judged; the rest stay null with reason: request_cap and status: partial, and you are charged only for the rows judged. Per-account daily allowances also apply; see AI pricing.

When nothing could be judged#

strict decides what happens when not a single row could be judged, because enrichment is off for the account, the provider is unavailable or a daily allowance is used up.

• strict=true (the default): the call fails, so you never mistake unjudged rows for judged ones. It is AI_UNAVAILABLE (503) or AI_BUDGET_EXCEEDED (429). When enrichment is not enabled at all, this is refused before the data is fetched, so it costs nothing.
• strict=false: you get the rows back, computed.labels is null on each, labels.status is unavailable with a reason, and there is no extra charge. Use it when the rows matter more than the judgments.

A partial result is never an error, whichever you choose: you get what was judged, status: partial and the reason.

Batch, multi-platform search and streams#

• Batch. Put the parameters in an item's params. The summary blocks sit on that item's row, not at the top of the response.
• Multi-platform search. include=labels and label= on /v1/search/multi apply to every platform whose search endpoint accepts them. Each platform's row carries its own labels block and extra_credits, and data.labels adds them up (legs, the counters, and unsupported: the platforms whose search has no enrichment, whose rows come back untouched). data.labels.status is complete only when every platform is.
• Streams. With Accept: text/event-stream the platform frames arrive first, without the enrichment lines in their credits_charged, then fused, then one enrich frame per step, then done with the full total. See Streaming.
• Idempotency. A replay with the same Idempotency-Key returns the stored body, labels included, at 0 credits. Changing any enrichment parameter makes it a different request (IDEMPOTENCY_KEY_REUSED).

What it costs#

The endpoint's own price, plus a separate charge for each step that judged something. It depends on how many rows are judged and how many presets you ask for, and it is reserved before judging and settled to what was actually used. Cached judgments, skipped rows and unjudged rows are free. Details and the measured examples are on AI pricing.

Errors it can return#

See Errors for the full list.