# Beatra MCP — Public social data

> Search public social content, read posts, creators, comments, and engagement, then continue into Beatra understanding and creation.
> Self-contained workflow guide for MCP clients and AI agents.
> Human-readable page: https://docs.beatra.ai/en/docs/capabilities/social

- Primary agent surface: authenticated MCP at `https://mcp.beatra.ai/mcp`.
- Discover tools: `beatra.social.tools.search` then `beatra.social.tools.get`.
- Billable action: `beatra.social.execute`.
- Interaction model: copy `schema_hash` from `tools.get`, create one opaque `client_request_id`, submit once, then poll `beatra.tasks.get` until terminal.
- This capability has no model field and no public REST API.

This MCP capability does not depend on an installable Skill package.

---

## 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:

1. Search available tools with `beatra.social.tools.search` — by platform,
   keyword, or type (`content`, `creator`, `comments`, `trends`, `captions`).
2. Inspect one tool with `beatra.social.tools.get`. Confirm the credit
   price, then copy the returned `schema_hash` and argument list.
3. Call `beatra.social.execute` once with `operation_key`, that `schema_hash`,
   `arguments`, and one `client_request_id`.
4. 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`.

## Tool arguments

```json
{
  "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

See `beatra.social.tools.search` and `beatra.social.tools.get` for the live tool list, arguments, `schema_hash`, and credit price.

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](https://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`.

---

## Appendix: shared social MCP contract

### Retry identity

One logical social lookup has one `client_request_id`. If the create response is
lost, retry the exact same arguments with that ID. If any tool, `schema_hash`,
or argument changes, use a new ID. Never create another paid task merely
because the first task is `queued` or `running`.

### Polling and billing truth

Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`,
`failed`, or `canceled`. The task is authoritative for the JSON result or
artifact, charged credits, and refunded credits. A successful lookup is billed
at the credit price returned by `beatra.social.tools.get`. Failed or safely
canceled tasks refund the hold.

### Recovery

Preserve structured Beatra error codes. Reconnect on authentication failure;
stop and request a balance action on insufficient balance; call
`beatra.social.tools.get` again after `schema_hash` or argument validation
fails. When a lookup fails after it started, keep the error `code` and read
`error.message` — that message is the platform wording after safety
redaction. Change arguments only when the message names a field or ID;
otherwise wait or keep polling the same task. Changed arguments always
require a new `client_request_id`.