100 free credits. No credit card required.Start building
Logo
Back to blog

Sponsored Post Detection API: Flag Undisclosed Ads

··10 min read

Flag sponsored posts and undisclosed ads in TikTok, X, YouTube and Reddit search results with a score, a disclosure flag and a brand, then drop engagement bait.

Sponsored Post Detection API: Flag Undisclosed Ads

To flag sponsored posts and undisclosed ads in bulk, search TikTok, X, YouTube or Reddit with label=sponsored,intent,niche. Each post comes back with computed.labels.sponsored: a probability p that the post is a paid or gifted promotion, a flag for whether a disclosure marker was found, a flag for likely paid posts with no marker, and the brand being promoted. Add label=quality and exclude=engagement_bait and engagement bait is dropped from the same result.

p is a probability. You choose the cut-off, and a person reviews what you flag. It does not read the video, only the caption (the title on YouTube). The same label slot can also score whether a post reads as machine-written, covered in AI Content Detector API.

A coarse net catching a few coral cards while most plain cards slip past, like a hashtag filter missing undisclosed ads

Why does a #ad hashtag filter miss undisclosed ads?

Searching #ad finds only the creators who disclosed the way you thought to look for. A European Commission sweep with consumer authorities in 22 Member States, Norway and Iceland checked 576 influencers: 97% posted commercial content and only 20% systematically disclosed it, according to its press release. 38% skipped platform labels such as Instagram's paid partnership label and wrote "collaboration" or a thank-you to the brand instead.

The FTC's influencer guidelines, in its Endorsement Guides Q&A, say that a platform offering a disclosure feature is "no guarantee that it's an effective way for influencers to disclose their material connection to a brand." A post that starts with #ad or "Ad:" would likely be effective, and #ambassador is ambiguous.

So a detector has to read the caption and work out which brand is being thanked. For influencer marketing work, the labels sit on the post rows you already pull.

Name the labels you want in the search. Sponsored, intent and niche are on by default, but naming them judges every row in the same response instead of letting slower rows finish on a later call, and it costs nothing extra.

bash
curl -G -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  "https://www.socialcrawl.dev/v1/tiktok/search" \
  --data-urlencode "query=#ad skincare serum gifted" \
  --data-urlencode "label=sponsored,intent,niche" \
  --data-urlencode "label_evidence=1"

A post with a disclosure marker, trimmed:

json
{
  "post": {
    "content": { "text": "Once you see the glow, there's no going back. #ad #brandpartner #skincare" }
  },
  "computed": {
    "labels": {
      "sponsored": { "p": 0.85, "disclosed": true, "undisclosed": false, "brand": null },
      "niche": { "label": "beauty_skincare", "confidence": 1, "taxonomy": "sc-niche-v1" }
    },
    "labels_evidence": {
      "sponsored": { "quote": "#ad #brandpartner #skincare", "sentence_index": 1 }
    }
  }
}

A creator who films for a brand and names it without any marker, the case a hashtag filter cannot see:

json
{
  "computed": {
    "labels": {
      "sponsored": { "p": 0.85, "disclosed": false, "undisclosed": true, "brand": "@brandname" }
    }
  }
}
FieldMeaning
pProbability from 0 to 1 that the post is a paid or gifted promotion
disclosedtrue when a disclosure marker such as #ad or 광고 was found in the text
undisclosedtrue when p is 0.7 or higher and no marker was found
brandThe mentioned account the post promotes, or null

label_evidence=1 adds computed.labels_evidence, the sentence that most clearly shows the label, copied verbatim. It is null when no single sentence shows it.

What do disclosed and undisclosed get wrong?

disclosed and undisclosed come from a text rule that looks for a marker, while p is the model's judgment. They can disagree, so read them together.

  • undisclosed: true means no recognised marker was found. It does not mean the creator hid anything, and disclosed: true means a marker was found, not that it is adequate under FTC or ASA rules.
  • brand comes from the post's own @mentions, so a mention that is cut short or missing gives a short or empty brand. Check it against your own brand list.
  • Neither flag sees a disclosure made only by voice in the video, or only through the platform's paid partnership toggle.

What niche and intent does each post carry?

computed.labels.niche is one of 33 topic niches such as beauty_skincare, or personal_no_niche or other, from the published sc-niche-v1 taxonomy. computed.labels.intent.label is one of asking_for_recommendation, comparing_options, switching_away, complaining, promoting, news_or_discussion or other. Both are null when the caption is too thin to tell.

A sponsorship-tracking job can keep niche.label == "beauty_skincare" and sponsored.p >= 0.5. A lead-finding job can keep intent.buyer == true.

A funnel diverting hook-shaped engagement bait cards into a side tray while normal posts pass through

How do you filter engagement bait out of a search result?

Meta's transparency center defines engagement bait as posts that "explicitly request engagement (such as votes, shares, comments, tags, likes, or other reactions)". Giveaway posts are the classic case.

label=quality adds five fields under computed.labels.quality: fact_density (an integer from 0 to 3), engagement_bait, rage_bait and secondhand (each 0 to 1), and post_aim (inform, opinion, sell, entertain, provoke or other).

bash
curl -G -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  "https://www.socialcrawl.dev/v1/tiktok/search" \
  --data-urlencode "query=giveaway follow like tag 3 friends to win" \
  --data-urlencode "label=sponsored,intent,niche,quality" \
  --data-urlencode "exclude=engagement_bait"

exclude=engagement_bait drops posts whose engagement_bait is 0.8 or higher, and it only works together with label=quality. The dropped rows are listed in data.labels.dropped_ids, and data.labels.dropped holds the count. Read those two rather than the top-level data.dropped. In a social media monitoring API job, this keeps bait out of the dataset you store. If a row near the line matters to you, skip exclude and apply your own cut-off to quality.engagement_bait.

Can the API flag rage bait?

Yes, as a score. quality.rage_bait runs from 0 to 1 and measures whether the writing is built to provoke anger, never which side the post takes. post_aim: "provoke" marks posts written to start a fight. There is no exclude=rage_bait, so filter on the score yourself.

Read computed.labels.quality.rage_bait on each row and keep rows below your cut-off, such as 0.5. Rows with no quality block count as 0, so unlabeled rows stay in.

Which platforms return these labels?

Post lists carry the default labels on TikTok, X, YouTube, Reddit, Instagram, Threads, LinkedIn, Facebook and Hacker News search endpoints, for example /v1/tiktok/search, /v1/twitter/search/tweets, /v1/youtube/search and /v1/reddit/search. The labels docs list every endpoint.

How much does sponsored post detection cost?

sponsored, intent and niche are free, with or without naming them. quality is metered. The call holds a few extra credits up front (4 on most lists, 5 on tiktok/search) and refunds down to 1 credit per started 25 rows it newly judged. Rows already judged for anyone are free, and so is a cached page. data.labels.extra_credits reports what the labels added.

To see the ceiling first, add dry_run=1. It quotes the call for 0 credits and fetches nothing:

bash
curl -G -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  "https://www.socialcrawl.dev/v1/tiktok/search" \
  --data-urlencode "query=#ad skincare serum gifted" \
  --data-urlencode "label=quality" \
  --data-urlencode "dry_run=1"

The estimate shows base_credits and a label_credits_min to label_credits_max range.

How do you run your first labeled call?

Create an API key (auth is the x-api-key header, one key for every platform), run the first curl above and read computed.labels.sponsored on each row. The explorer shows the payload before you write a line, and the TikTok search reference lists every parameter.

Frequently asked questions

How do I find sponsored posts in bulk on TikTok, X, YouTube or Reddit?

Send the search call with label=sponsored,intent,niche, read computed.labels.sponsored.p on each row and keep the rows above your cut-off. disclosed and undisclosed say whether a disclosure marker was found.

How can I tell if a post is a paid or gifted promotion?

The API has no field that separates paid from gifted. It returns one score, p, with disclosed, undisclosed and brand. Read the label_evidence quote and the caption to decide which kind of deal it was.

What is engagement bait and how do I filter it from search results?

Meta defines engagement bait as posts that explicitly request votes, shares, comments, tags, likes or other reactions. Ask for label=quality and exclude=engagement_bait in the same call. Rows scoring 0.8 or more are dropped, and their ids appear in data.labels.dropped_ids.

Not with a parameter, since exclude takes engagement_bait only. Request label=quality, read computed.labels.quality.rage_bait on each row and filter in your own code, for example below 0.5.

How much does it cost to label sponsored posts?

sponsored, intent and niche are free. quality holds a few extra credits and refunds down to 1 credit per started 25 rows newly judged. A dry_run=1 call quotes the range for 0 credits.

Are undisclosed ads illegal?

It depends on the country and the post. The FTC's Endorsement Guides expect a clear disclosure of a material connection to a brand. This post is not legal advice, and a label from this API is evidence for a reviewer to check.

Topics
#undisclosed-ads#sponsored-post-detection#engagement-bait#engagement-baiting#sponsored-posts#ftc-influencer-guidelines#rage-bait#instagram-paid-partnership-label

Related posts

🤖 AI agent or LLM? Read this page as markdown