Social Data API | BeatAPI API Documentation

BeatAPI Social Data is a synchronous, developer-facing API for retrieving public data from supported social platforms. You use a BeatAPI API key and a BeatAPI-owned action ID; provider accounts, routing, and upstream response details stay behind the API.

Quick start

Choose an action from the Social Data action catalog, then send its action ID and parameters:

curl https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"douyin.web.fetch_one_video","params":{"aweme_id":"7364837462110"}}'

The public endpoint is POST /v1/social-data/call. The model field is not required for this endpoint; the action ID selects the operation. Do not send provider-native URLs or provider-native route names.

Request

Field	Type	Required	Description
`action`	string	Yes	BeatAPI action ID from the catalog.
`params`	object	No	Parameters described by the selected catalog entry. Omit it when the action has no parameters.

action must use the catalogued identifier format, such as douyin.web.fetch_one_video. The catalog entry’s input_schema is the source of truth for required fields, types, and allowed values. For actions whose catalog method is GET, parameter values are scalar. For POST actions, params is a JSON object.

The request body is limited to 512 KiB. Authentication uses Authorization: Bearer <BeatAPI API key>. You may send Idempotency-Key when your client may retry the same request; reusing that key with a different request is rejected.

Response

Successful calls return the normalized BeatAPI envelope:

{
  "object": "social_data.call",
  "status": "succeeded",
  "request_id": "req_01H...",
  "action": "douyin.web.fetch_one_video",
  "data": {
    "aweme_id": "7364837462110"
  }
}

data is the public result returned for the selected action. BeatAPI removes provider names, provider request IDs, cache URLs, routing fields, and raw provider error details before returning it. The response is synchronous: a successful HTTP response means the action has completed.

Errors and credits

Errors use the normal BeatAPI error envelope and a stable code:

HTTP status	Code	Meaning
400 / 422	`bad_request`	Invalid JSON, action, or parameters.
401 / 403	`processing_unavailable`	Authentication or access cannot be completed.
402	`insufficient_credits`	The account does not have enough credits.
404	`not_found`	The requested action or resource was not found.
409	`idempotency_conflict`	The idempotency key was reused with a different request.
429	`rate_limit_exceeded`	The request limit was reached.
5xx	`processing_unavailable`	The request could not be completed.

Failed calls do not consume credits. A successful call consumes credits according to the account’s current BeatAPI pricing and the selected action. Supplier costs and supplier URLs are never part of this documentation or public response.

MCP

The same catalog and contract are available through the capabilities_search, capabilities_inspect, and capabilities_run MCP tools. MCP clients should use the data:<action-id> capability reference returned by Inspect; they do not need provider credentials or provider-native paths.