# Social (/docs/social) Social is a CoreSpeed-hosted research capability. Its 43 tools read **public** data from nine platforms on CoreSpeed's own supplier accounts, so there is no OAuth grant to obtain and nothing for the agent to log in to. Every tool is read-only and typed per platform: the inputs are the platform's own identifiers and cursors, not a free-form URL to an arbitrary endpoint. Tool names follow `social___`. The wire names and exact parameters come from `tools/list`; the tables below are the map. ## Tools by platform \[#tools-by-platform] ### TikTok \[#tiktok] | Tool | Returns | | ------------------------------- | --------------------------------------------------------------------------------- | | `social__tiktok_video_by_url` | One video from a public share URL — author, stats, music, play and download URLs. | | `social__tiktok_profile` | A profile by `user_id`, `sec_user_id`, or `unique_id` (the @handle). Exactly one. | | `social__tiktok_user_videos` | A user's videos; paginate with `max_cursor`. | | `social__tiktok_video_comments` | Comments on a video by `aweme_id`; paginate with `cursor`. | | `social__tiktok_search_videos` | Keyword search with region, recency, and sort filters. | ### Douyin \[#douyin] | Tool | Returns | | ------------------------------- | ---------------------------------------------------------- | | `social__douyin_video_by_url` | One video or image post from a share URL or share text. | | `social__douyin_profile` | A profile by `sec_user_id`. | | `social__douyin_user_videos` | A user's videos; paginate with `max_cursor`. | | `social__douyin_video_comments` | Comments on a video by `aweme_id`; paginate with `cursor`. | | `social__douyin_hot_search` | The current hot-search ranking board. | ### Xiaohongshu \[#xiaohongshu] | Tool | Returns | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `social__xiaohongshu_search_notes` | Keyword search with sort, type, and time filters. Later pages pass back the `search_id` and `search_session_id` the first page returned. | | `social__xiaohongshu_profile` | A profile by `user_id` or profile share text. Exactly one. | | `social__xiaohongshu_user_notes` | A user's public notes; paginate with `cursor`. | | `social__xiaohongshu_note_comments` | Comments on a note by `note_id` or share text; paginate with `cursor`. | A nonexistent Xiaohongshu id still answers `200` upstream, so the request bills like any other successful one. ### Instagram \[#instagram] | Tool | Returns | | --------------------------------- | --------------------------------------------------------------------------------------- | | `social__instagram_search` | Accounts, hashtags, and places for a query; paginate with `next_max_id` + `rank_token`. | | `social__instagram_profile` | A profile by `username`. | | `social__instagram_user_posts` | A user's posts; paginate with `after` / `before`. | | `social__instagram_post` | One post by `media_id` or public post URL. Exactly one. | | `social__instagram_post_comments` | Comments on a post by its shortcode; paginate with `min_id`. | Instagram tools bill at the premium rate (below). ### YouTube \[#youtube] | Tool | Returns | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `social__youtube_search` | Videos, channels, and playlists with upload-date, type, duration, and sort filters; paginate with `continuation_token`. | | `social__youtube_video` | Metadata for one video by `video_id` or `video_url` — title, channel, stats, description, formats. | | `social__youtube_video_comments` | Comments on a video; paginate with `continuation_token`. | | `social__youtube_channel_videos` | A channel's videos by `channel_id`; paginate with `continuation_token`. | | `social__youtube_captions` | Caption languages for a video, or one transcript as `srt`, `xml`, `json3`, or `txt`. Premium rate. | | `social__youtube_captions_result` | Collects a captions job that answered `processing`. Free. | ### X \[#x] | Tool | Returns | | ------------------------- | --------------------------------------------------------------------------------------------------------- | | `social__x_post` | One public post by numeric `tweet_id`. | | `social__x_profile` | A profile by `screen_name` or numeric `rest_id`. Exactly one. | | `social__x_user_posts` | A user's public posts; paginate with `cursor`. | | `social__x_search` | Keyword search — `search_type` is `Top`, `Latest`, `Media`, `People`, or `Lists`; paginate with `cursor`. | | `social__x_post_comments` | Replies to a post; paginate with `cursor`. | | `social__x_trending` | Trending topics for a `country`. | ### Reddit \[#reddit] | Tool | Returns | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `social__reddit_search` | Posts, communities, comments, media, or people for a query; paginate with `after`. | | `social__reddit_post` | One post by id (`t3_…` or bare), optionally focused on one comment. | | `social__reddit_post_comments` | Comments on a post; paginate with `after`. | | `social__reddit_subreddit` | Public information about a subreddit (name without `r/`). | | `social__reddit_subreddit_feed` | A subreddit's posts — `sort` is `BEST`, `HOT`, `NEW`, `TOP`, `CONTROVERSIAL`, or `RISING`; paginate with `after`. | | `social__reddit_profile` | A user profile (name without `u/`). | | `social__reddit_user_posts` | A user's posts; paginate with `after`. | ### Facebook \[#facebook] | Tool | Returns | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `social__facebook_page` | A public Page's profile — category, about text, website, email, phone, address, likes, followers, rating, and whether it is running ads. `page` is the Page URL or username. | | `social__facebook_page_posts` | A Page's recent posts — text, media links, reactions, comment and share counts. `limit` up to 100; optional `newer_than` / `older_than`. | | `social__facebook_post_comments` | Comments on a public post by `post_url`, sorted `most_relevant`, `newest`, or `all`; optionally with replies. | | `social__facebook_ads` | The Meta Ad Library: ads matching a keyword `query` (optionally in one `country`), or one advertiser `page`'s ads — creative, landing links, platforms, dates, active status. Exactly one of `query` or `page`. | ### Threads \[#threads] | Tool | Returns | | ------------------------- | ---------------------------------------------------------------------------------------- | | `social__threads_profile` | A public profile by `username` — display name, bio, follower count, links, verification. | Facebook and Threads tools run a live collection rather than a single request; see [below](#facebook-and-threads-run-a-live-collection). ## Responses are JSON, and they can be large \[#responses-are-json-and-they-can-be-large] Each tool returns the platform's payload as compact JSON text. Feeds carry many CDN URLs, so every tool accepts `max_characters` — default 200,000, hard cap 600,000. A clipped response ends with an explicit truncation notice that says so; raise `max_characters` or narrow the request (a smaller `count`, one page) to see the rest. Cursors are the platform's own and are returned in the payload; pass them back verbatim. ## YouTube captions are asynchronous \[#youtube-captions-are-asynchronous] `social__youtube_captions` without `language_code` lists the caption languages a video has. With one, it returns that transcript. A large video comes back as `{ "status": "processing", "job_id": "…" }` instead — collect it with `social__youtube_captions_result`, a single non-blocking poll: `queued` or `active` means try again in 2–5 seconds, `completed` carries the transcript in `content`. Only captions the video already has are returned; there is no speech-to-text, and a video without captions still bills the request. ## Facebook and Threads run a live collection \[#facebook-and-threads-run-a-live-collection] These tools gather their results live, which typically takes 10–60 seconds. They answer `{ "complete": true, "count": …, "results": [ … ] }`. Each accepts `timeout_seconds` (default 50, max 240) — how long the collection may run. At that deadline the results gathered so far come back with `"complete": false`, and only those are billed; a collection that found nothing in time answers `timeout` and bills nothing. Raise `timeout_seconds` only if your client allows tool calls that long, or lower `limit` for a complete answer sooner. A collection that fails upstream answers `collection_failed`, also uncharged. ## Pricing and holds \[#pricing-and-holds] Exactly one charge per **successful** request, at the endpoint's own rate: | Tools | Charge | | --------------------------------------------------- | ----------------------- | | Everything not listed below | 1.5 credits per request | | `youtube_search` | 3 credits per request | | The five `instagram_*` tools and `youtube_captions` | 12 credits per request | | The four `xiaohongshu_*` tools | 15 credits per request | | `youtube_captions_result` | 0 | Facebook and Threads bill per result the collection returns: | Tool | Charge | | ------------------------ | -------------------------------------------------------------------------------- | | `facebook_page` | 18 credits per page | | `facebook_page_posts` | 7.5 credits per post, plus 1.5 per run; 3 more per post with a date filter | | `facebook_post_comments` | 3.75 credits per comment, plus 1.5 per run; 3 more per comment with `newer_than` | | `facebook_ads` | 8.7 credits per ad | | `threads_profile` | 7.5 credits per profile | A failed request — network error, upstream rejection, or arguments that fail the tool's schema — never charges. The live figure is in each tool's description in `tools/list`, and each charge lands in the organization ledger labelled by platform (`tiktok`, `xiaohongshu`, `facebook`, …); see [Billing & credits](/docs/billing). An organization billing hold or suspension stops a social call before it runs, as an `isError` result carrying `payment_required` or `org_suspended`, and API-key spend caps apply the same way. ## What is deliberately not exposed \[#what-is-deliberately-not-exposed] Account and login helpers, private-message deep links, an arbitrary-endpoint proxy, and any engagement-manipulation endpoint. The surface is public research data only, and the typed inputs are what keep it that way. ## Controls \[#controls] Social appears as **Social media research** in [Dashboard → Tools](https://app.corespeed.io/tools). Turning it off hides every `social__*` tool from `tools/list` for that member; see [Capability controls](/docs/capability-controls).