Public social data

Search public social content, read posts, creators, comments, and engagement, then continue into Beatra understanding and creation.

Primary agent path

Public social data uses the same Beatra OAuth MCP connection as images, video, music, and speech. You do not add a second server. Connect https://mcp.beatra.ai/mcp, then:

Search available tools with beatra.social.tools.search — by platform, keyword, or type (content, creator, comments, trends, captions).
Inspect one tool with beatra.social.tools.get. Confirm the credit price, then copy the returned schema_hash and argument list.
Call beatra.social.execute once with operation_key, that schema_hash, arguments, and one client_request_id.
Poll beatra.tasks.get until the task is terminal. The result is inline JSON or a JSON artifact.

One execute is one prepaid task and one lookup. The next page of a list is another execute.

AI guide

MCP integration guide for AI

For custom API integrations, copy this guide into Claude, Codex, or another coding assistant.

Markdown

Tool arguments

{
  "operation_key": "social.tiktok.video.get_by_id",
  "schema_hash": "sha256:…",
  "arguments": { "aweme_id": "…" },
  "client_request_id": "social-lookup-opaque-1"
}

Use the schema_hash that beatra.social.tools.get just returned. If get returns a new hash, send a new client_request_id.

What you can look up

The table is a snapshot of current tools. Live price, arguments, and schema_hash always come from beatra.social.tools.get.

TikTok

Tool	Type	What it returns	Credits	Paging
`social.tiktok.video.get_by_id`	content	Read one public TikTok video by aweme_id, including caption, author, metrics, and public media URLs.	6	No
`social.tiktok.video.get_by_url`	content	Read one public TikTok video from a share URL, including caption, author, metrics, and public media URLs.	6	No
`social.tiktok.user.get`	creator	Read a public TikTok profile by unique_id or sec_user_id.	6	No
`social.tiktok.user.posts.list`	content	Read one page of a user's public TikTok videos and the next cursor.	6	Yes
`social.tiktok.video.search`	content	Search public TikTok videos by keyword and return one billed page.	6	Yes
`social.tiktok.user.search`	creator	Search public TikTok users by keyword and return one billed page.	6	Yes
`social.tiktok.video.comments.list`	comments	Read one page of public top-level comments on a TikTok video.	6	Yes
`social.tiktok.comment.replies.list`	comments	Read one page of public replies to a TikTok comment.	6	Yes
`social.tiktok.hashtag.trends.list`	trends	Read public TikTok hashtag trend rankings for a country and time range.	6	Yes

Douyin

Tool	Type	What it returns	Credits	Paging
`social.douyin.video.get_by_url`	content	Read one public Douyin post from a share URL, including media URLs.	6	No
`social.douyin.video.get_by_id`	content	Read one public Douyin post by aweme_id, including media URLs.	6	No
`social.douyin.user.get`	creator	Read a public Douyin profile by sec_user_id.	6	No
`social.douyin.user.posts.list`	content	Read one page of a user's public Douyin posts and the next cursor.	6	Yes
`social.douyin.video.search`	content	Search public Douyin videos by keyword and return one billed page.	60	Yes
`social.douyin.user.search`	creator	Search public Douyin users by keyword and return one billed page.	6	Yes
`social.douyin.video.comments.list`	comments	Read one page of public top-level comments on a Douyin video.	6	Yes
`social.douyin.comment.replies.list`	comments	Read one page of public replies to a Douyin comment.	6	Yes
`social.douyin.hot_search.list`	trends	Read the current public Douyin hot-search board.	6	No

Xiaohongshu

Tool	Type	What it returns	Credits	Paging
`social.xiaohongshu.note.image.get`	content	Read one public Xiaohongshu image note, including image URLs and metadata.	60	No
`social.xiaohongshu.note.video.get`	content	Read one public Xiaohongshu video note, including cover and video URLs.	60	No
`social.xiaohongshu.user.get`	creator	Read a public Xiaohongshu profile.	60	No
`social.xiaohongshu.user.notes.list`	content	Read one page of a user's public notes.	60	Yes
`social.xiaohongshu.note.search`	content	Search public Xiaohongshu notes by keyword and return one billed page.	60	Yes
`social.xiaohongshu.user.search`	creator	Search public Xiaohongshu users by keyword and return one billed page.	60	Yes
`social.xiaohongshu.note.comments.list`	comments	Read one page of public top-level comments on a note.	60	Yes
`social.xiaohongshu.comment.replies.list`	comments	Read one page of public replies to a note comment.	60	Yes
`social.xiaohongshu.topic.get`	trends	Read a public Xiaohongshu topic and its metadata.	60	No
`social.xiaohongshu.topic.notes.list`	content	Read one page of public notes under a topic.	60	Yes

Instagram

Tool	Type	What it returns	Credits	Paging
`social.instagram.post.get`	content	Read one public Instagram post or Reel, including media URLs.	12	No
`social.instagram.user.get`	creator	Read a public Instagram profile.	12	No
`social.instagram.user.posts.list`	content	Read one page of a user's public posts.	12	Yes
`social.instagram.user.reels.list`	content	Read one page of a user's public Reels.	12	Yes
`social.instagram.user.search`	creator	Search public Instagram users by keyword.	12	No
`social.instagram.reel.search`	content	Search public Instagram Reels by keyword and return one billed page.	12	Yes
`social.instagram.hashtag.posts.list`	content	Read one page of public posts for a hashtag.	12	Yes
`social.instagram.post.comments.list`	comments	Read one page of public comments on a post.	12	Yes
`social.instagram.comment.replies.list`	comments	Read one page of public replies to a comment.	12	Yes

YouTube

Tool	Type	What it returns	Credits	Paging
`social.youtube.video.get`	content	Read public YouTube video metadata, statistics, and thumbnails.	6	No
`social.youtube.video.comments.list`	comments	Read one page of public YouTube comments.	6	Yes
`social.youtube.comment.replies.list`	comments	Read one page of public YouTube comment replies.	6	Yes
`social.youtube.video.captions.get`	captions	Submit one caption request and receive the available public captions for a video.	60	No
`social.youtube.channel.resolve`	creator	Resolve a public channel URL or handle to a channel_id.	6	No
`social.youtube.channel.get`	creator	Read a public YouTube channel description and statistics.	6	No
`social.youtube.channel.videos.list`	content	Read one page of a channel's public videos.	6	Yes
`social.youtube.channel.shorts.list`	content	Read one page of a channel's public Shorts.	6	Yes
`social.youtube.video.search`	content	Search public YouTube videos and return one billed page of video items.	12	Yes

X / Twitter

Tool	Type	What it returns	Credits	Paging
`social.twitter.tweet.get`	content	Read one public X/Twitter post, including media URLs.	6	No
`social.twitter.user.get`	creator	Read a public X/Twitter profile.	6	No
`social.twitter.user.tweets.list`	content	Read one page of a user's public posts.	6	Yes
`social.twitter.user.media.list`	content	Read one page of a user's public media posts.	6	Yes
`social.twitter.user.replies.list`	comments	Read one page of a user's public replies.	6	Yes
`social.twitter.tweet.comments.list`	comments	Read one page of public replies to a post.	6	Yes
`social.twitter.tweet.search.top`	content	Search public X/Twitter posts with Top ranking and return one billed page.	6	Yes
`social.twitter.tweet.search.recent`	content	Search public X/Twitter posts by recency and return one billed page.	6	Yes
`social.twitter.trends.list`	trends	Read public trending topics for a country.	6	No

Typical successful payloads include:

post or note text, author identity, and public statistics
comment and reply text with public engagement counts
captions or subtitles when the selected tool returns them
public media URLs (play, cover, image) you can fetch or pass to beatra.images.understand, beatra.videos.understand, or a generation tool

Small results are inlined on the task. Larger results are stored as a JSON artifact and linked from the task. Open Activity in the console to read the same payload.

Price

Each successful lookup costs one of these credit amounts, confirmed before the task is created:

Credits per successful lookup
6
12
30
60

Failed or safely canceled tasks refund the hold. After the lookup has started, cancel returns 409 — keep polling the same task. Social tasks have no model field.

Billing, task status, and recovery

queued and running are not failures. If the create response is lost, retry the identical arguments with the same client_request_id. Any changed argument requires a new ID.

Situation	What to do
`402 insufficient_balance`	Top up at console.beatra.ai, then retry the same `client_request_id`. Nothing was charged.
`invalid_request` on arguments	Call `beatra.social.tools.get` and send only the published fields.
Tool not found or not available	Search again; use an `operation_key` that `tools.get` reports as available.
`schema_hash` no longer matches	Call `tools.get` again and submit a new `client_request_id`.
Lost create response	Retry the identical execute with the same `client_request_id`.
`409` on cancel	The lookup already started. Keep polling the same task.

When a lookup fails after it started, keep the error code and read error.message. That message is the platform's wording after safety redaction. Change arguments only when the message names a field or ID; otherwise wait or keep polling the same task.

REST API

There is no public Social REST API. Use MCP plus beatra.tasks.get.