InsightSocial APILabels
Model judgments on comment lists, post lists and post search results. On by default, no extra credits, and one parameter turns them off.
Comment lists, post lists and post search lists come back with labels attached: the tone of a comment, whether a post is paid promotion, whether a search result is actually about what you searched for. Default labels are on automatically, cost no extra credits, and leave every existing field untouched.
curl "https://api.insightsocial.app/v1/tiktok/post/comments?url=https://www.tiktok.com/@khaby.lame/video/7462093158820417811" \
-H "x-api-key: $INSIGHTSOCIAL_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": 20,
"credits_remaining": 9480,
"request_id": "req_1a2b3c4d5e6f",
"cached": false,
"idempotent_replay": false,
"charge_reason": "miss",
"free_call": false
}The response is cut down to one comment and its values are illustrative. The call cost the same as it would without labels. Every comment now has a computed.labels object. The data.labels summary counts the judged rows and the ones still pending, and extra_credits: 0 confirms the labels cost nothing extra.
Each judgment comes from putting a single, tightly scoped question about a row to a model, for example whether a comment is a question. It comes back as a probability between 0 and 1, or as a level, so you pick the threshold. Everything else is plain code: choosing which rows to send, counting, the drops you request, and the credits. Treat labels as signals, not verdicts on a post or a person.
Default labels per list
| List | Default labels (no extra credits) | Where they appear |
|---|---|---|
| Comment lists | sentiment, question, purchase_intent, complaint | items[].computed.labels, summarized in data.labels |
| Post lists | sponsored, intent (without fits_offer), niche | items[].computed.labels, summarized in data.labels |
| Post search lists | relevance to your query, as a score only: nothing is removed or reordered | items[].computed.relevance, summarized in data.relevance |
Comment lists: /v1/tiktok/post/comments, /v1/tiktok/video/comment/replies, /v1/instagram/post/comments, /v1/instagram/post/comment/replies, /v1/youtube/video/comments, /v1/youtube/video/comment/replies, /v1/reddit/post/comments, /v1/facebook/post/comments, /v1/facebook/post/comment/replies, /v1/twitter/tweet/replies.
Post lists: /v1/instagram/profile/posts, /v1/instagram/profile/reels, /v1/instagram/search/reels, /v1/tiktok/profile/videos, /v1/tiktok/search/hashtag, /v1/twitter/user/tweets, /v1/twitter/search/tweets, /v1/reddit/search, /v1/reddit/subreddit, /v1/facebook/search/posts, and four search lists that read several pages per call: /v1/tiktok/search, /v1/youtube/search, /v1/threads/search, /v1/linkedin/search/posts.
Post search lists (relevance): /v1/instagram/search/reels, /v1/twitter/search/tweets, /v1/facebook/search/posts, /v1/reddit/search, /v1/tiktok/search, /v1/youtube/search, /v1/threads/search, /v1/linkedin/search/posts.
Endpoints not listed here behave as they always have and take no judgments parameter.
Field shapes
Inside computed.labels, every preset writes to a key with its own name. If a preset's key is absent, that preset has not reached the row yet.
Comments
| Label | Value | Meaning |
|---|---|---|
sentiment | { level, score_0_1, confidence } | Tone of the comment on five levels, 0 (very negative) to 4 (very positive). score_0_1 is the same reading on a 0 to 1 scale. |
question | { p } | A genuine question. Rhetorical questions that mock or complain do not count. |
purchase_intent | { p } | The author bought, ordered or is switching to the thing, or asks for a link or price. "Is it worth it?" does not count. |
complaint | { p } | Something went wrong for the author personally. Criticizing a price or a spec does not count. |
Posts
| Label | Value | Meaning |
|---|---|---|
sponsored | { p, disclosed, undisclosed, brand } | p: paid or gifted promotion. disclosed: it carries a marker such as #ad or 광고. undisclosed: likely paid with no marker. brand: the mentioned account being promoted, or null. |
intent | { label, confidence, buyer, seller, urgency, fits_offer } | The author's main purpose: asking_for_recommendation, comparing_options, switching_away, complaining, promoting, news_or_discussion, other, or null when unclear. buyer and seller say which side they read as, and urgency runs 0 to 3. fits_offer stays null unless you send offer=. |
niche | { label, confidence, taxonomy } | The caption's niche in the published is-niche-v1 taxonomy, or personal_no_niche, or other. label is null when the caption is too thin. Only the caption is read, never the video. |
Post search relevance
items[].computed.relevance is { p, sense, depth, spam }:
p: probability that the row is about what your query means.sense: what the query's key word refers to in this row.targetmeans the row uses it in your sense;other_named_thingmeans a different brand, person or place that shares the name;generic_wordmeans it is used as an ordinary word;not_presentmeans it does not appear.depth: from 0 (not about it) to 3 (mainly about it).spam: probability that the row is a mass-posted template.
A row with too little text carries relevance: null.
null and pending
A null label means the row was not judged in this response. That is not the same as a low score: { "p": 0.02 } means "judged, and no", while null means "not judged yet". If we could not judge a row, you still get it back, and it adds nothing to the cost of the call.
Default labels run under a short time limit so they never slow the page down. On list endpoints, rows that are not finished in time are sent with labels: null (or relevance: null), counted in data.labels.pending, listed in pending_ids, and keep being judged after the response goes out. Results are stored per row, so your next call for the same page carries them, including a cached response. In practice a comment page usually arrives fully labeled on the first call, while a post page often arrives mostly pending and is complete on the next. At most 60 new rows are started per request, so a long page may take a few calls to fill; rows beyond that are counted as unjudged, not pending.
data.labels.status gives the overall picture:
status | Meaning |
|---|---|
complete | Every row that can be judged has its labels. |
partial | Some rows are null, either still in progress (pending) or not judged this time (unjudged). |
skipped | Judging was turned off for this request because capacity was short. No row carries labels, not even earlier ones, so the page looks like a judgments=off page plus the report. |
To get every row labeled in the same response, name the labels: label=sentiment,question,purchase_intent,complaint still adds no credits, and named labels are judged before the response is sent, with a longer time limit. relevance=score does the same for search relevance.
The report
data.labels summarizes the labels on the page:
| Field | Meaning |
|---|---|
presets | Which labels the report covers. |
mode | default when you sent no label=, requested when you did. |
status | complete, partial or skipped, as above. |
rows | Rows on the page before anything was dropped. |
labelled, cached | labelled: rows with all their labels filled. cached: how many of those labels were reused from earlier judgments. |
pending, pending_ids | Rows still being judged when the page was sent. |
unjudged, skipped | unjudged: rows left without a judgment in this response. skipped: deleted or empty rows, which we never judge and never charge for. |
dropped, dropped_ids | Rows removed by an exclude= you sent. Default labels never drop rows. |
extra_credits | Credits the labels added to this call. Always 0 for default labels. |
methodology_version | Identifies the question set behind the labels. A new value means the questions changed. |
default | Only when you named some labels: a separate report, with its own mode, status, pending and pending_ids, for the default labels you did not name. Absent when you named all of them. |
On post search lists, data.relevance has the same status, pending and pending_ids, plus origin (default or requested), since its mode field already holds score or filter.
Turning labels off
curl "https://api.insightsocial.app/v1/tiktok/post/comments?url=https://www.tiktok.com/@khaby.lame/video/7462093158820417811&judgments=off" \
-H "x-api-key: $INSIGHTSOCIAL_API_KEY"judgments=off returns the page without any labels: no computed.labels, no computed.relevance, no data.labels and no data.relevance. On list endpoints label=none has the same effect, even inside a list such as label=mention,none. Requests with and without off are cached separately, so turning labels off never hands you a labeled page from the cache. It does not cancel a label= or relevance= sent in the same request; those still run.
Adding labels with label=
Named labels are added on top of the defaults:
curl "https://api.insightsocial.app/v1/instagram/search/reels?query=buldak+noodles&label=mention&brand=Buldak" \
-H "x-api-key: $INSIGHTSOCIAL_API_KEY"Each reel keeps sponsored, intent, niche and its relevance score, and gains mention: is the post about Buldak or about something with the same name, how it feels about the brand, which aspect it discusses, and whether the author bought or used it. data.labels reports the labels you named (mode: "requested"), and data.labels.default reports the defaults. A row can carry the named labels now and the defaults on a later call.
Opt-in labels with extra credits
Labels that need input from you, or that have not been measured blind yet, run only when you ask.
| Request with | On | Adds |
|---|---|---|
label=mention&brand= | post lists | mention: about the brand or not, sentiment toward it, sarcasm, aspect discussed, first-hand use |
label=intent&offer= | post lists | intent.fits_offer: whether your offer could plausibly help this author |
label=spam, label=toxic, label=low_quality | comment lists | { p } for each (low_quality also adds generic and bait). exclude=spam or exclude=low_quality removes rows scoring 0.8 or higher. |
relevance=score or relevance=filter with relevant_to= | post search lists | relevance to a topic you describe, instead of to the query |
These labels are charged by the rows they actually judge: 20 credits for each started block of 25 rows newly judged in the request, up to 80 extra credits on most lists, 100 on /v1/tiktok/search and 160 on /v1/linkedin/search/posts. Rows already judged earlier cost nothing, and a page where nothing could be judged adds nothing. The total for the call never goes above the endpoint's listed maximum price. Naming a label that is also a default, such as label=sponsored, stays free. The credits used appear in data.labels.extra_credits.
Filtering by relevance
With relevance=filter, off-topic rows are taken out of the page, and the IDs of everything removed are listed in data.relevance.dropped_ids. With your query as the topic it adds no credits.
curl "https://api.insightsocial.app/v1/instagram/search/reels?query=mustang+horse&relevance=filter" \
-H "x-api-key: $INSIGHTSOCIAL_API_KEY"A row is kept when its p is 0.5 or higher, or above the relevance_threshold you set. Pagination is not affected, so a filtered page can hold fewer rows than usual. Rows we could not judge always stay in the page.
Credits and caching
Default labels never change what a call costs: it is charged exactly as the same call with judgments=off. Labels survive caching: we keep each row's judgment for 30 days against the exact text, so a cached page comes back labeled and a comment whose text changed gets a new judgment. Cached responses are priced as described in Caching. See Credits for how calls are charged; API credits are non-refundable, and calls that fail or return nothing are never charged.
How reliable labels are
We switch a label on by default only after checking it against rows that people labeled by hand. Some labels hold up better than others, and results vary by language, niche and query, so check a sample against your own data before you act on a label, and keep a person in the loop for decisions that matter.
spam and toxic are rare in real data, so there are not enough true examples to check them properly. That is why they stay off unless you request them with label=.