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

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:

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`.

## AI guide

AI integration guide: https://docs.beatra.ai/llms/social.md

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

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

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`.