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.

Writing-pattern labels: ai_style

label=ai_style flags writing patterns that are common in AI-generated text, such as "This is not X. It's Y." and "Here's what nobody tells you". It reads the text of each post and nothing else. It does not say who wrote the post, and a person who writes in this style is flagged too. Read it as a list of patterns you can check in the text, never as a verdict on an author.

curl "https://www.socialcrawl.dev/v1/twitter/search/tweets?query=customer+feedback&label=ai_style&exclude=ai_style" \
  -H "x-api-key: YOUR_API_KEY"

exclude=ai_style only works together with label=ai_style in the same request. Sent alone it returns a 400 and costs nothing. Dropped posts are listed in data.labels.dropped_ids, and a post that could not be judged is never dropped.

Each post carries computed.labels.ai_style:

A pattern counts as present when:

• a judged pattern (the first six) is 0.8 or higher;
• slop_words is 1 or more;
• em_dashes is 2 or more;
• emoji_bullets is 2 or more;
• one_line_paragraphs is 5 or more.

exclude=ai_style drops a post with a pattern_count of 2 or more. The thresholds are published so you can recompute pattern_count from the fields beside it, or apply your own cut-off to the raw numbers and skip exclude= altogether.

A trimmed example row, illustrative and not a recorded response:

{
  "post": {
    "id": "1234567890",
    "content": { "text": "Listening to customers is smart.\n\nObeying every customer request isn't.\n\n..." }
  },
  "computed": {
    "labels": {
      "ai_style": {
        "binary_contrast": 0.91,
        "faux_insight": 0.06,
        "colon_reveal": 0.03,
        "profound_kicker": 0.12,
        "puffery": 0.02,
        "rhetorical_setup": 0.18,
        "slop_words": 0,
        "em_dashes": 0,
        "emoji_bullets": 0,
        "one_line_paragraphs": 7,
        "pattern_count": 2,
        "markers": "binary_contrast,one_line_paragraphs"
      }
    }
  }
}

What to know before you rely on it:

• Short posts are counted, not judged. A post with fewer than about eight words of prose (links, hashtags and mentions do not count) is never sent to the model. Its six judged fields are 0, and the four counted fields are still filled in, so it can still reach a pattern_count of 2.
• A long post is read at both ends. The judged patterns read the first 400 characters of the post and its last 150, so a closing line is judged too, and the counts read the whole post. A pattern that sits only in the middle of a long post is judged from the counts alone.
• Paragraph layout matters. one_line_paragraphs splits at blank lines. A post that breaks its lines with single newlines scores 0 there, and a list with blank lines between its items can score high.
• fields= removes the labels. A fields= projection keeps only the paths you name on each row, and computed.labels.ai_style is not one of them unless you add it. The drop and data.labels.dropped_ids still apply, so rows disappear without a reason. Name the label to keep it: add fields=post.url,post.published_at,post.content.text,computed.labels.ai_style to the call above. The path is computed.labels.ai_style, not post.computed.labels.ai_style: on a row, computed sits beside post, not inside it. A path that matches nothing is named in data._warnings, with the path it suggests.

Where it works. Every post list that takes label=, including /v1/twitter/search/tweets, /v1/twitter/user/tweets and /v1/linkedin/search/posts. It is not a default label.

What it costs. It is metered like the other opt-in post labels: the call holds a few extra credits up front and settles at 1 credit per started 25 posts newly judged on that request. Posts already labelled for anyone, and a cached page, cost nothing extra. data.labels.extra_credits reports what the label added, and dry_run=1 shows the ceiling first.

AI-written detection: ai_written

label=ai_written scores how likely each post was written by an AI model. It comes from SocialCrawl's own text classifier, trained for this one question, not from a general-purpose language model. Where ai_style names patterns you can check in the text, ai_written is the probability those patterns only hint at.

curl "https://www.socialcrawl.dev/v1/linkedin/search/posts?query=product+feedback&label=ai_written&exclude=ai_written" \
  -H "x-api-key: YOUR_API_KEY"

Each post carries computed.labels.ai_written:

exclude=ai_written drops likely posts. To drop more, add ai_written_threshold= with the p you want to drop at, for example ai_written_threshold=0.71 to drop possible posts too. A post too short to read, or one that could not be scored, is never dropped. Like every exclude=, it works only together with label=ai_written in the same request.

To check one text you already have, without a list, call /v1/utility/ai-detection?text=. It returns the same judgment for the same text, for 1 credit.

How accurate it is. Measured on 467 posts the model never saw: 233 written by people before ChatGPT existed (X and Reddit, up to November 2022), and 234 written by 8 current models (GPT-5.5, GPT-5.4 mini, GPT-4o mini, gpt-oss, Claude Sonnet 4.5, Claude Haiku 4.5, Gemini 3 Flash, Grok 4.3), a third of them prompted to sound like a person.

What to know before you rely on it:

• It is a probability, not proof. A person can be flagged and an AI-written post can pass. Use it to filter or sort a feed, not to accuse anyone of anything.
• Short posts are the hardest. Under about 40 words, likely catches about 2 in 5 AI posts. Under 8 words the model does not guess: level is too_short.
• Some models are harder to catch than others. Of the 8 tested, Gemini 3 Flash was the hardest: 28% likely, 79% possible or above.
• Edited text sits in between. A draft a person rewrote, or a person's post polished by AI, can land anywhere on the scale.
• It reads the opening of each post, about the first 1,000 characters, which on social posts is nearly always the whole post.
• English is what it was measured on. It returns a score for any language, but other languages are unmeasured.

What it costs. Metered like the other opt-in post labels: 1 credit per started 25 posts newly judged on that request, so a 20-post page adds 1 credit. Posts already scored for anyone, and a cached page, cost nothing extra.

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. The numbers were measured again on 16/10/2026, when the judging model was updated. The search/everywhere stance, search/creators account kind and prism/comment-leads rows are from the earlier model; their blind sets have not been run again yet.

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