---
name: buzztake
description: Use when a user wants you to post, reply, like, follow, message, read or search on their own social media accounts, or to add such an account, through BuzzTake.
---

# BuzzTake

BuzzTake makes your user's social media accounts available to you. It keeps each account signed in, in its own remote browser, and runs what a person can do there.

Platforms: `x` (X), `instagram` (Instagram), `facebook` (Facebook), `linkedin` (LinkedIn), `tiktok` (TikTok), `threads` (Threads), `bluesky` (Bluesky), `reddit` (Reddit), `youtube` (YouTube), `pinterest` (Pinterest), `mastodon` (Mastodon), `telegram` (Telegram).

## Hosts and auth

- API: https://api.buzztake.com. Send `Authorization: Bearer btk1_...`.
- MCP: https://mcp.buzztake.com/mcp, streamable HTTP, same header.
- Web app: https://buzztake.com. The user creates API keys and tops up there.

## Add an account

`POST https://api.buzztake.com/v1/workspaces/{workspace_id}/accounts`

```json
{
  "platform": "x",
  "label": "Brand main",
  "connect": { "method": "password", "username": "acme_demo", "password": "...", "totp_secret": "JBSW..." },
  "proxy": "http://user:pass@203.0.113.7:8000"
}
```

`connect.method`:
- `password`: `username`, `password`, optional `totp_secret`. BuzzTake answers 2FA codes itself.
- `cookies`: `cookies`, a JSON array of cookie objects or a Netscape cookie file string.
- `browser`: a person signs in live through `sign_in_url`.

Other fields:
- `instance`: Mastodon only, the server origin, such as `https://mastodon.social`.
- `proxy`: optional URL (`http`, `https`, `socks5`, `ss`, `vless`, `vmess`, `trojan`, `hysteria2`) or `null`.
- `device`: `linux`, the default and only value. Fixed for the life of the account.
- `label`: optional, at most 80 characters.

Answer `201`: `{ "account": {...}, "action": { "type": "connect", ... }, "sign_in_url": "..." }`. `sign_in_url` is present for `browser` and when a challenge appears. It opens a live browser for that one account for 30 minutes, without a BuzzTake login. Give it to the person who owns the account.

Account statuses:
- `connecting`: BuzzTake is signing in.
- `active`: Signed in and ready.
- `needs_input`: A sign-in challenge waits for an answer.
- `signed_out`: Cookies expired and no stored credentials could sign in again.
- `blocked`: The platform shows a checkpoint on the account.
- `error`: Something failed that BuzzTake could not classify.

Account routes:
- `GET /v1/workspaces/{ws}/accounts?platform=&status=`: list, newest first.
- `GET /v1/accounts/{id}`, `DELETE /v1/accounts/{id}`.
- `PATCH /v1/accounts/{id}`: `label`, `proxy`, `credentials` (`{username,password,totp_secret}` or `null`).
- `POST /v1/accounts/{id}/connect`: sign in again, same `connect` body. Returns an action.
- `POST /v1/accounts/{id}/check`: is it still signed in? Returns an action.
- `POST /v1/accounts/{id}/sign-in-links`: a new `sign_in_url`.

Credentials are stored encrypted and never returned. The account shows `has_credentials`.

## Run an action

`POST https://api.buzztake.com/v1/accounts/{id}/actions`

```json
{ "type": "post", "text": "Hello", "media": ["0199..."], "wait": 60 }
```

- Parameters sit at the top level, beside `type`.
- `wait`: seconds, max 120. Finished in time: `200`. Else `202`; poll `GET /v1/actions/{id}?wait=30`.
- Header `Idempotency-Key`: a retry with the same key does not run the action twice.
- The answer is an Action: `id`, `account_id`, `type`, `status`, `params`, `result`, `error`, `challenge`, `credits`, `created_at`, `started_at`, `finished_at`.
- `status`: `queued`, `running`, `needs_input`, `succeeded`, `failed`, `canceled`.
- Same action on many accounts: `POST /v1/workspaces/{ws}/actions` with `account_ids`. Answer: `{ "actions": [...] }`.
- History: `GET /v1/accounts/{id}/actions`, `GET /v1/workspaces/{ws}/actions` (`limit`, `cursor`, `status`).
- Cancel a `queued` or `needs_input` action: `POST /v1/actions/{id}/cancel`.
- Media ids come from `POST /v1/workspaces/{ws}/media` (upload intent, PUT the file to `upload_url`, POST `finalize_url`).

## Actions

| type | parameters | credits | does |
|---|---|---|---|
| `post` | `text`, `media[]`, `title`, `link`, `destination`, `visibility`, `thread[]` | 10 | Publish a new post, with media, a title, a link, a destination or a thread. |
| `reply` | `target`, `text`, `media[]` | 8 | Reply to a post, by its URL. |
| `quote` | `target`, `text`, `media[]` | 10 | Share a post with your own text above it. |
| `delete_post` | `target` | 3 | Delete one of the account's own posts. |
| `repost` | `target` | 3 | Repost a post as it is. |
| `unrepost` | `target` | 3 | Remove a repost. |
| `like` | `target` | 3 | Like a post. |
| `unlike` | `target` | 3 | Remove a like. |
| `bookmark` | `target` | 3 | Save a post to the account's bookmarks. |
| `unbookmark` | `target` | 3 | Remove a saved post. |
| `follow` | `user` | 3 | Follow a person, by handle or profile URL. |
| `unfollow` | `user` | 3 | Stop following a person. |
| `block` | `user` | 3 | Block a person. |
| `unblock` | `user` | 3 | Remove a block. |
| `mute` | `user` | 3 | Mute a person. |
| `unmute` | `user` | 3 | Remove a mute. |
| `send_message` | `to`, `text`, `media[]` | 10 | Send a direct message to a handle, a profile or an open conversation. |
| `list_conversations` | `limit` | 4 | Read the inbox: the latest conversations, newest first. |
| `read_conversation` | `conversation`, `limit` | 4 | Read the messages in one conversation. |
| `read_feed` | `limit` | 4 | Read the account's home feed as the platform shows it. |
| `read_notifications` | `limit` | 4 | Read the latest notifications. |
| `read_post` | `target`, `replies` | 4 | Read one post and its replies. |
| `read_profile` | `user`, `limit` | 4 | Read a profile and its latest posts. Without `user`, the account itself. |
| `list_followers` | `user`, `limit` | 4 | List the people who follow a profile. |
| `list_following` | `user`, `limit` | 4 | List the people a profile follows. |
| `search` | `query`, `kind`, `limit` | 4 | Search posts or people. |
| `update_profile` | `display_name`, `bio`, `website`, `location`, `avatar`, `banner` | 10 | Change the display name, bio, website, location, avatar or banner. |
| `browser` | `steps[]` | 2 per run, plus 1 per step | Run your own steps in the signed-in browser, for anything without a named action. |

Parameters:
- `target`: a post URL. `user`: a handle or profile URL (reads default to the account itself).
- `to`: a handle, profile URL, or conversation URL or id. `conversation`: a URL, id or handle.
- `limit`: default 20, max 100. `replies`: default 20. `kind`: `posts` or `people`.
- `media[]`, `avatar`, `banner`: media ids. `thread[]`: texts that continue the post, in order.
- `title`, `link`, `destination` (subreddit, board, Page, group or channel), `visibility`: where the platform has them.

`result.type`: `created` (`url`, `id`), `done` (`changed`), `posts`, `post` (`item`, `replies`), `users`, `profile`, `conversations`, `messages`, `notifications`, `browser` (`steps`). Lists are in `items`. Fields the page does not show are `null`.

### Browser steps

For anything without a named action:

```json
{ "type": "browser", "wait": 90, "steps": [
  { "op": "goto", "url": "https://x.com/settings" },
  { "op": "perceive" },
  { "op": "click", "node": "f1:42" },
  { "op": "click", "locator": { "role": "button", "name": "Save" } },
  { "op": "type", "text": "hello", "locator": { "role": "textbox" } },
  { "op": "press", "key": "enter" },
  { "op": "scroll", "dy": 800 },
  { "op": "wait", "ms": 1500 },
  { "op": "extract", "container": { "role": "article" }, "fields": [ { "key": "text", "locator": {}, "source": { "kind": "text" } } ] },
  { "op": "screenshot" }
] }
```

Result: `{ "type": "browser", "steps": [ { "op": "perceive", "ok": true, "perception": {...} }, { "op": "screenshot", "ok": true, "image_url": "..." } ] }`. The session stays warm for 2 minutes after a run.

## Challenges

When a sign-in needs a person, the action stops at `needs_input` with `challenge`: `kind`, `message`, `expires_at`, `sign_in_url`.

- `two_factor_code`: A code from an authenticator app.
- `email_code`: A code the platform sent by email.
- `sms_code`: A code the platform sent by text message.
- `device_approval`: Approve the sign-in on another device.
- `captcha`: A puzzle the platform shows to a new sign-in.
- `other`: Anything else the page asks for. The message says what.

Answer with `POST /v1/actions/{id}/answer` and `{ "answer": "123456" }`, or give your user `sign_in_url`. `device_approval` and `captcha` usually need the live browser. Unanswered by `expires_at`: `challenge_timeout`.

## Errors

`error`: `{ "code": "...", "message": "..." }`.

- `signed_out`: The account is signed out and no stored credentials could sign it in again.
- `login_failed`: The platform refused the username, password or code.
- `account_blocked`: The platform shows a checkpoint or a suspension on the account.
- `rate_limited`: The platform asked the account to slow down. Try again later.
- `not_found`: The post, person or conversation does not exist or is not visible to the account.
- `unsupported`: This platform has no such action.
- `invalid_input`: A parameter is missing or has the wrong shape.
- `rejected`: The platform refused the action, for example a duplicate post.
- `ui_changed`: The page did not look the way the driver expects. We are told and fix it.
- `challenge_timeout`: A sign-in challenge was not answered before it expired.
- `browser_unavailable`: No browser could be started. Nothing was charged; try again.
- `browser_error`: The browser failed while running the action.
- `insufficient_credits`: The balance is too low for this action. Top up and try again.

## Credits

- 1 credit = USD 0.01. Whole credits only.
- Writes are charged when they start running. A failed write before any page change is refunded.
- Reads are charged on success only.
- Account prices: `connect` 25 per sign-in attempt, `check` 1, `live` 2 per started minute.
- Scheduled calendar posts are charged as `post` per account.
- `GET /v1/credits`: `{ "balance": 1234, "low_balance_threshold": 100 }`.
- `GET /v1/prices`: every price. Public.
- Top up with x402: an x402 payment adds whole credits. Payment requirements: https://api.buzztake.com/.well-known/x402. People can top up in the web app.

## MCP

https://mcp.buzztake.com/mcp. Each action `type` is a tool, plus `send_feedback`. `tools/list` gives the live set and input schemas. A tool result carries any challenge and its `sign_in_url`. Credits are the same as REST.

## Feedback

When a user asks for something no action covers, or a result looks wrong, tell us: `POST /v1/feedback` or MCP `send_feedback`.

```json
{ "kind": "missing_capability", "message": "User asked to schedule a TikTok live; no action exists.",
  "context": { "tool": "post", "platform": "tiktok", "action_id": null } }
```

`kind`: `bug`, `missing_capability`, `improvement`, `other`.

## Docs

- Overview: https://buzztake.com/docs
- Quickstart: https://buzztake.com/docs/quickstart
- MCP server: https://buzztake.com/docs/mcp
- Accounts: https://buzztake.com/docs/accounts
- Actions: https://buzztake.com/docs/actions
- Errors and challenges: https://buzztake.com/docs/errors
- Credits and x402: https://buzztake.com/docs/credits
- Feedback: https://buzztake.com/docs/feedback
- Index: https://buzztake.com/docs/llms.txt