DocumentationActions

Actions

One endpoint for everything an account can do. type names the action.

Request

POST/v1/accounts/{id}/actions

Request

curl https://api.buzztake.com/v1/accounts/$ACCOUNT_ID/actions \
  -H "Authorization: Bearer $BUZZTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-post-1" \
  -d '{ "type": "post", "text": "Hello", "media": ["0199f7a8-..."], "wait": 60 }'

type: The action. See the reference below.
wait: Seconds to hold the request, max 120. Omit it to get 202 at once.
Idempotency-Key: Header. A retry with the same key does not run the action twice.
other fields: The action's parameters, at the top level.

Action object

200 when it finished inside wait, else 202. Same object.

Action

{
  "id": "0199e5f6-...",
  "account_id": "0199a1b2-...",
  "type": "post",
  "status": "succeeded",
  "params": { "text": "Hello", "media": ["0199f7a8-..."] },
  "result": { "type": "created", "url": "https://x.com/acme_demo/status/1", "id": "1" },
  "error": null,
  "challenge": null,
  "credits": 10,
  "created_at": "2026-10-14T09:00:00Z",
  "started_at": "2026-10-14T09:00:01Z",
  "finished_at": "2026-10-14T09:00:09Z"
}

status: queued, running, needs_input, succeeded, failed, canceled. Meanings, error and challenge: Errors and challenges.

Results

result.type says the shape. Fields the page does not show are null.

Type	Fields	From
`created`	`url`, `id`	`post`, `reply`, `quote`, `send_message`
`done`	`changed`: `false` when the account was already in that state	Other writes
`posts`	`items`: posts	`read_feed`, `search` with `kind: posts`
`post`	`item`, `replies`	`read_post`
`users`	`items`: people	`list_followers`, `list_following`, `search` with `kind: people`
`profile`	`profile`	`read_profile`
`conversations`	`items`: conversations	`list_conversations`
`messages`	`items`: messages	`read_conversation`
`notifications`	`items`: notifications	`read_notifications`
`browser`	`steps`: one entry per step	`browser`

Charges

Kind	Charged
Write	When it starts running. A failed write is refunded if no page changed.
Read	On success only.

All prices: Credits.

Publish

`post`

Publish a new post, with media, a title, a link, a destination or a thread. Write, 10 credits ($0.10).

text: The text.
media[]: Array of media ids from the media upload.
title: A title, where the platform has one. On Mastodon: the content warning.
link: A link, such as a Pin link or a Reddit link post.
destination: Where to post when not on the account itself: a subreddit, board, Page, group or channel.
visibility: A visibility word the platform knows, such as public, followers or unlisted.
thread[]: Array of texts that continue the post as a thread, in order.

`reply`

Reply to a post, by its URL. Write, 8 credits ($0.08).

target: The post URL.
text: The text.
media[]: Array of media ids from the media upload.

`quote`

Share a post with your own text above it. Write, 10 credits ($0.10).

target: The post URL.
text: The text.
media[]: Array of media ids from the media upload.

`delete_post`

Delete one of the account's own posts. Write, 3 credits ($0.03).

target: The post URL.

Engage

`repost`

Repost a post as it is. Write, 3 credits ($0.03).

target: The post URL.

`unrepost`

Remove a repost. Write, 3 credits ($0.03).

target: The post URL.

`like`

Like a post. Write, 3 credits ($0.03).

target: The post URL.

`unlike`

Remove a like. Write, 3 credits ($0.03).

target: The post URL.

`bookmark`

Save a post to the account's bookmarks. Write, 3 credits ($0.03).

target: The post URL.

`unbookmark`

Remove a saved post. Write, 3 credits ($0.03).

target: The post URL.

People

`follow`

Follow a person, by handle or profile URL. Write, 3 credits ($0.03).

user: A handle or profile URL.

`unfollow`

Stop following a person. Write, 3 credits ($0.03).

user: A handle or profile URL.

`block`

Block a person. Write, 3 credits ($0.03).

user: A handle or profile URL.

`unblock`

Remove a block. Write, 3 credits ($0.03).

user: A handle or profile URL.

`mute`

Mute a person. Write, 3 credits ($0.03).

user: A handle or profile URL.

`unmute`

Remove a mute. Write, 3 credits ($0.03).

user: A handle or profile URL.

Messages

`send_message`

Send a direct message to a handle, a profile or an open conversation. Write, 10 credits ($0.10).

to: A handle, a profile URL, or a conversation URL or id.
text: The text.
media[]: Array of media ids from the media upload.

`list_conversations`

Read the inbox: the latest conversations, newest first. Read, 4 credits ($0.04).

limit: How many items. Default 20, max 100.

`read_conversation`

Read the messages in one conversation. Read, 4 credits ($0.04).

conversation: A conversation URL, id or handle.
limit: How many items. Default 20, max 100.

Read

`read_feed`

Read the account's home feed as the platform shows it. Read, 4 credits ($0.04).

limit: How many items. Default 20, max 100.

`read_notifications`

Read the latest notifications. Read, 4 credits ($0.04).

limit: How many items. Default 20, max 100.

`read_post`

Read one post and its replies. Read, 4 credits ($0.04).

target: The post URL.
replies: How many replies to read. Default 20.

`read_profile`

Read a profile and its latest posts. Without user, the account itself. Read, 4 credits ($0.04).

user: A handle or profile URL. Default: the account itself.
limit: How many items. Default 20, max 100.

`list_followers`

List the people who follow a profile. Read, 4 credits ($0.04).

user: A handle or profile URL. Default: the account itself.
limit: How many items. Default 20, max 100.

`list_following`

List the people a profile follows. Read, 4 credits ($0.04).

user: A handle or profile URL. Default: the account itself.
limit: How many items. Default 20, max 100.

`search`

Search posts or people. Read, 4 credits ($0.04).

query: The search text.
kind: posts or people.
limit: How many items. Default 20, max 100.

Profile

`update_profile`

Change the display name, bio, website, location, avatar or banner. Write, 10 credits ($0.10).

display_name: New display name.
bio: New bio.
website: New website.
location: New location.
avatar: A media id.
banner: A media id.

Browser

`browser`

Run your own steps in the signed-in browser, for anything without a named action. Browser, 2 credits per run, plus 1 per step.

steps[]: The steps to run. See Browser steps below.

Browser steps

type: "browser" runs your steps in the account's signed-in browser. Use it for anything without a named action.

Body

{ "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" }
] }

op	Fields	Does
`goto`	`url`	Open a page.
`perceive`		Read the page. Returns a `perception` with node ids, such as `f1:42`.
`click`	`node` or `locator`	Click a node from `perceive`, or the element a locator finds.
`type`	`text`, `locator`	Type into a field.
`press`	`key`	Press a key, such as `enter`.
`scroll`	`dy`	Scroll by pixels.
`wait`	`ms`	Wait.
`extract`	`container`, `fields`	Read each matching container into named fields.
`screenshot`		Returns an `image_url`.

result

{
  "type": "browser",
  "steps": [
    { "op": "perceive", "ok": true, "perception": { "...": "..." } },
    { "op": "screenshot", "ok": true, "image_url": "https://..." }
  ]
}

The session stays warm for 2 minutes after a run, so the next call starts at once. Price: 2 credits per run, plus 1 per step.

History and control

Route	Does
`GET /v1/actions/{id}?wait=30`	One action. Waits up to `wait` seconds while it is `queued` or `running`.
`GET /v1/accounts/{id}/actions?limit=&cursor=`	Account history, newest first.
`GET /v1/workspaces/{ws}/actions?limit=&cursor=&status=`	Workspace history.
`POST /v1/actions/{id}/answer`	`{ "answer": "123456" }` for a `needs_input` action.
`POST /v1/actions/{id}/cancel`	Cancel a `queued` or `needs_input` action.
`POST /v1/workspaces/{ws}/actions`	One action on many accounts. See Batch.

Batch

POST/v1/workspaces/{ws}/actions

The same action on many accounts. Each account gets its own action and charge.

Request

curl https://api.buzztake.com/v1/workspaces/$WORKSPACE_ID/actions \
  -H "Authorization: Bearer $BUZZTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_ids": ["0199a1b2-...", "0199b2c3-..."],
    "type": "like",
    "target": "https://x.com/acme_demo/status/1"
  }'

Answer (trimmed)

{ "actions": [
  { "id": "0199d1e2-...", "account_id": "0199a1b2-...", "type": "like", "status": "queued" },
  { "id": "0199d3e4-...", "account_id": "0199b2c3-...", "type": "like", "status": "queued" }
] }