SocialToAIStart freeConsole

search

POST /v1/search is the search action: find posts or accounts by keyword. It is offered on 16 platforms (TikTok, Instagram, X, Reddit, YouTube, LinkedIn and 10 more), and the platform is a parameter of the request. One call costs 2 to 12 credits, depending on the platform; a call that fails costs nothing.

POSThttps://socialtoai.app/v1/search

Request

A JSON body. These are the same for every action; the rest depends on the platform, below.

NameTypeWhereRequiredWhat it is
platformstringbodyYesThe platform to read. One of the platforms this action is offered on.
limitintegerbodyNoOf search, trending, comments and user_posts: how many items you want. Pages are fetched one after another in the one call until there are that many or no more, each page charged as a call; pages not needed cost 0.
max_cost_creditsintegerbodyNoThe most this call may cost. Over it, the call is refused for free and the answer carries the quote.
Idempotency-KeystringheaderNo1 to 255 visible ASCII characters. The same key with the same parameters returns the first result again and is not charged twice.

Platforms and credits

Each platform takes its own parameters. Its own page has the full parameter and field tables and a request you can change.

PlatformPrice keyCreditsRequiredOptionalPer page
TikToktiktok.search2querysort, published_within30
Instagraminstagram.search:user3query, type=user–50
Xx.search2querysort20
Redditreddit.search2querysort, published_within25
YouTubeyoutube.search2querysort, published_within100
LinkedInlinkedin.search2querypublished_within10
Threadsthreads.search2querysince, until20
Pinterestpinterest.search2query–50
Xiaohongshuxiaohongshu.search12querysort, type, published_within20
Douyindouyin.search12querysort, published_within20
Weiboweibo.search2query–20
WeChat Articleswechat.search12querysort, published_within, type30
Bilibilibilibili.search2querysort20
Zhihuzhihu.search2querytype, sort20
Kuaishoukuaishou.search12querysort, published_within, duration20
WeChat Channelswechat_channels.search12querysort, published_within20

Some platforms have another form of this action, selected by a parameter and priced on its own:

PlatformPrice keyCreditsSelected by
TikToktiktok.search:user2type=user
Xx.search:latest2sort=latest
Xx.search:user5type=user
YouTubeyoutube.search:user2type=user
Xiaohongshuxiaohongshu.search:user12type=user
Xiaohongshuxiaohongshu.search:image12type=image
Douyindouyin.search:user2type=user
Weiboweibo.search:user2type=user
WeChat Articleswechat.search:user12type=user
Zhihuzhihu.search:user2type=user
Kuaishoukuaishou.search:user12type=user
WeChat Channelswechat_channels.search:user36type=user

Parameters

NameTypeWhat it isTaken by
querystringSearch termsAll
sortstringBy relevance, by likes, or newest first Values vary by platform: relevance, popular, latest, most_comments, most_favorites, most_followers, fewest_followersTikTok, X, Reddit, YouTube, Xiaohongshu, Douyin, WeChat Articles, Bilibili, Zhihu, Kuaishou and WeChat Channels
published_withinstringOnly videos posted within this period Values vary by platform: day, week, month, half_year, yearTikTok, Reddit, YouTube, LinkedIn, Xiaohongshu, Douyin, WeChat Articles, Kuaishou and WeChat Channels
sincedatetimePublished on or after this day (filtered by UTC date; the time of day is ignored)Threads
untildatetimePublished on or before this day (filtered by UTC date; the time of day is ignored)Threads
typestringVideo notes only (video) or image notes only (image); both when left out Values vary by platform: video, image, article, answerXiaohongshu, WeChat Articles and Zhihu
durationstringOnly videos of this length band; any length when left out Values vary by platform: under_1_min, 1_to_5_min, over_5_minKuaishou
filterstringOnly one kind of account: verified, the verified ones; live, the ones live now; any when left out Values vary by platform: verified, liveKuaishou
genderstringOnly female or only male users (as they give it on their profiles) Values vary by platform: female, maleKuaishou

Example

TikTok: Find videos by keyword: text, author, likes, comment count, views and publish time.

curl https://socialtoai.app/v1/search \  -H "Authorization: Bearer $SOCIALTOAI_API_KEY" \  -H "Idempotency-Key: $(uuidgen)" \  -H "Content-Type: application/json" \  -d '{    "platform": "tiktok",    "query": "space station"  }'
import osimport uuidimport requestsresponse = requests.post(    "https://socialtoai.app/v1/search",    headers={        "Authorization": f"Bearer {os.environ['SOCIALTOAI_API_KEY']}",        # A new key for each request; the same one again retries it without paying twice.        "Idempotency-Key": str(uuid.uuid4()),    },    json={        "platform": "tiktok",        "query": "space station",    },)print(response.json())
Response200 OK2 credits
{  "request_id": "req_00000000-0000-4000-8000-000000000001",  "schema_version": "v1",  "fetched_at": "2026-10-12T19:17:24.000Z",  "action": "search",  "platform": "tiktok",  "status": "ok",  "items": [    {      "platform": "tiktok",      "id": "…",      "ref": "…",      "approx": [],      "extra": {},      "type": "content",      "url": "https://example.com/…",      "format": "video",      "title": null,      "text": "…",      "published_at": "2026-10-11T23:17:34.000Z",      "author": {        "id": "…",        "username": "…",        "name": "…",        "verified": null,        "followers": 92601      },      "metrics": {        "likes": 353,        "comments": 11,        "shares": 19,        "collects": 40,        "views": 7561,        "reposts": null      },      "images": null,      "hashtags": ["…", "…"],      "is_pinned": null    }  ],  "unavailable": ["title", "author.verified", "metrics.reposts", "images", "is_pinned"],  "page": {    "has_more": true,    "cursor": "cur_…",    "cursor_expires_at": "2026-10-12T19:47:24.000Z"  },  "warnings": [],  "applied_params": {    "query": "space station"  },  "cost_credits": 2,  "billing": {    "cost_credits": 2,    "balance_credits": 98,    "today_spend_credits": 2,    "daily_limit_credits": null,    "daily_remaining_credits": null,    "display": "This call: 2 credits (≈ $0.0067). Balance: 98 credits (≈ $0.33)."  },  "replayed": false}

Sample data: names, links and text are replaced by placeholders.

What comes back

The envelope with content and account items. One call returns one page of up to 30 items; each page is its own call. A cursor works for up to 30 minutes.

A failed call costs 0 credits and says why: see Errors.

Last updated: