Labels and judgments

Comment, post, review and search lists come back with SocialCrawl labels attached: how a comment feels, whether a post is a paid promotion, which problem a review reports, whether a search result is about what you searched for. They are on by default, they add no credits, and every field you already read stays exactly as it was.

curl "https://www.socialcrawl.dev/v1/tiktok/post/comments?url=https://www.tiktok.com/@stoolpresidente/video/7623818255903329566" \
  -H "x-api-key: YOUR_API_KEY"

{
  "success": true,
  "platform": "tiktok",
  "endpoint": "/v1/tiktok/post/comments",
  "data": {
    "items": [
      {
        "comment": { "text": "Ordering it for my 13 year old ❤️" },
        "computed": {
          "language": "en",
          "labels": {
            "sentiment": { "level": 4, "score_0_1": 0.91, "confidence": 0.71 },
            "question": { "p": 0.03 },
            "purchase_intent": { "p": 0.98 },
            "complaint": { "p": 0.02 }
          }
        }
      }
    ],
    "labels": {
      "presets": ["sentiment", "question", "purchase_intent", "complaint"],
      "mode": "default",
      "status": "complete",
      "rows": 50,
      "labelled": 50,
      "cached": 0,
      "skipped": 0,
      "unjudged": 0,
      "pending": 0,
      "pending_ids": [],
      "dropped": 0,
      "dropped_ids": [],
      "extra_credits": 0,
      "methodology_version": "labels/1"
    }
  },
  "credits_used": 1,
  "cached": false
}

The response is trimmed to one comment, and the labels shown are the ones that comment received on a recorded run. The page cost 1 credit, the same as it did before labels existed. Each comment gained computed.labels, and data.labels reports how many rows were judged, how many are still waiting, and what the labels cost you (nothing: extra_credits: 0).

A judgment is a model's answer to one narrow question about one row ("is this comment asking a question?"), published as a probability from 0 to 1 or as a level, so you choose the cut-off. Code does everything else: which rows are worth sending, the counting, the drops you ask for, and the credits. Labels are signals to read, never a verdict on a post, a review or a person.

What each list gets by default

Prism composites already judged their rows before this change; see Prism.

Field shapes

Every label is a key under computed.labels, named after its preset. A preset key that is missing means that preset has not judged the row yet.

Comments

Posts

Post search relevance

items[].computed.relevance is { p, sense, depth, spam }. p is the probability that the row is about what your query means. sense says which thing the query's key word refers to in the row: target (what you meant), other_named_thing (a different brand, person or place with the same name), generic_word, or not_present. depth runs from 0 (not about it) to 3 (mainly about it), and spam is the probability that the row is a mass-posted template. A row with too little text to judge carries relevance: null.

Reviews

Search endpoints

On search/everywhere, on_topic: false marks exactly the results relevance=filter would drop. On search/creators, individual_creator is published only when the name, handle or bio shows one particular person; otherwise the creator reads cannot_tell.

null and pending

A row whose labels are null was not judged in this response. That is different from a low probability: { "p": 0.02 } means "judged, and no", null means "not judged yet". A label that could not be judged never drops a row and is never billed.

Default labels are judged under a short time budget so they never slow your page down. On list endpoints, rows not finished in time ship with labels: null (or relevance: null), are counted in data.labels.pending and listed in pending_ids, and keep being judged after the response is sent. The result goes into a shared per-row store, so your next call for the same page, including a free cache hit, carries them. In practice a cold comment page usually arrives fully labelled; a cold post or review page often arrives mostly pending and is complete from the next call. At most 60 cold rows are started per request, so a longer page can take more than one call to fill; rows past that count are unjudged, not pending.

data.labels.status sums it up:

Need every row labelled in this response? Ask for the labels by name: label=sentiment,question,purchase_intent,complaint is still free, and a label you ask for is judged in the foreground under a longer time budget. relevance=score does the same for search relevance.

The four search endpoints judge inside the request and keep no per-row store. A result not judged in time stays null for the life of that cached response (2 minutes, 5 minutes on search/news). There, a late or failed judgment is also named in data._warnings: stance_partial, stance_unavailable or stance_skipped on search/everywhere, stories_pending or stories_unavailable on search/news. search/forums and search/creators report it in status only.

The report

data.labels describes the labels on this page:

data.relevance on the post search lists has the same status, pending and pending_ids, plus origin (default or requested), because its mode field already says score or filter.

Turn them off

curl "https://www.socialcrawl.dev/v1/tiktok/post/comments?url=https://www.tiktok.com/@stoolpresidente/video/7623818255903329566&judgments=off" \
  -H "x-api-key: YOUR_API_KEY"

judgments=off returns the page exactly as it was before default labels: no computed.labels, no computed.relevance or computed.stance, no data.labels, data.relevance, data.stance_split, data.stories or account blocks. label=none does the same on list endpoints, also inside a list such as label=mention,none. It is part of the cache key, so an off request never receives a labelled cached page. It does not cancel a label= or relevance= you pass in the same request: those still run.

Ask for more: label= adds to the defaults

Naming labels adds them to the defaults rather than replacing them:

curl "https://www.socialcrawl.dev/v1/instagram/search/reels?query=buldak+noodles&label=mention&brand=Buldak" \
  -H "x-api-key: YOUR_API_KEY"

Each reel keeps sponsored, intent, niche and its relevance score, and gains mention: is the post about Buldak rather than something that shares the name, how it feels about the brand, which aspect it talks about, and whether the author bought or used it. data.labels reports the labels you named (mode: "requested"), and data.labels.default reports the default ones. A row can carry the labels you named now and the default ones on the next call.

What stays opt-in and metered

Labels that need your own input, and labels without a blind measurement yet, run only when you ask for them.

On the lists, a metered label holds a few extra credits up front (4 on most lists, 5 on tiktok/search, 8 on linkedin/search/posts) and refunds down to 1 credit per started 25 rows newly judged on this request. Rows already judged for anyone are free, a page where nothing could be judged refunds the whole hold, and a cached page is free. brief= on search/creators adds 2 credits. Asking by name for a label that is also a default one, such as label=sponsored, stays free.

Filtering is free

relevance=filter drops the rows that are not about your query and lists their ids in data.relevance.dropped_ids. It is free with your query as the topic.

curl "https://www.socialcrawl.dev/v1/instagram/search/reels?query=mustang+horse&relevance=filter" \
  -H "x-api-key: YOUR_API_KEY"

• Post search lists: a row is kept at p of 0.5 or more, or the relevance_threshold you set. Pagination is unchanged, so a filtered page can hold fewer rows.
• search/everywhere: drops the ranked results the ranking step already judged off-topic, inside the flat 20 credits. items_by_source is not filtered.
• search/forums: relevance=score reorders threads by relevance blended with their rank, and filter also drops the off-topic ones, inside the flat 10 credits.
• search/creators: relevance=filter works only with brief= and drops creators that do not fit it.

A row that could not be judged is never dropped.

Credits and caching

Default labels never add credits, holds or refunds: a call costs exactly what the same call costs with judgments=off. A response cache hit is still 0 credits and still labelled, because labels are read from a shared per-row store that lasts 30 days and is keyed by the row's text, so an edited comment is judged again. See Credits and Caching.

How we measure

A label is on by default only when it has a blind measurement: rows labelled by hand before any judgment ran on them, on queries and sources never used to write or tune the questions. Every number below comes from one labeller, not a panel, so read it as a strong signal rather than a guarantee, and keep a person in the loop for decisions that matter.

Two Prism composites that judge rows on request were measured the same way:

The default comment labels were measured on held-out rows of their tuning set rather than on a separate blind set, so their numbers are not quoted here. spam, toxic and incentivized have too few real positives in any set to measure, which is why they stay opt-in.

Next steps