Alerts

Create an alert

POST/v1/workspaces/{workspace_id}/alerts

curl https://api.buzztake.com/v1/workspaces/$WORKSPACE_ID/alerts \
  -H "Authorization: Bearer $BUZZTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_ids": ["0199a1b2-..."],
    "events": ["like", "reply", "message"],
    "webhook": false,
    "interval_minutes": 30
  }'

{
  "id": "0199e5f6-...",
  "workspace_id": "0199...",
  "account_ids": ["0199a1b2-..."],
  "events": ["like", "reply", "message"],
  "webhook": false,
  "interval_minutes": 30,
  "status": "active",
  "pause_reason": null,
  "created_by_user_id": "0199...",
  "last_checked_at": null,
  "next_check_at": "2026-10-13T20:30:00Z",
  "created_at": "2026-10-13T20:00:00Z",
  "updated_at": "2026-10-13T20:00:00Z"
}

pause_reason is null when the alert is active, userafter a pause request, and insufficient_credits when the balance could not pay a check.

Events

like

Someone liked a post of the account.

repost

Someone reposted a post of the account.

reply

Someone replied to the account.

mention

Someone mentioned the account.

quote

Someone quoted a post of the account.

follow

Someone followed the account.

message

A conversation is new or changed and its last message is not from the account.

timeline_post

A new post in the home feed (For you on X).

following_post

A new post of an account you follow (Following on X).

like to follow come from the notifications, messagefrom the conversations, timeline_post from the home feed (read_feedfor_you) and following_post from the feed of the accounts the user follows (read_feed following, on X and Mastodon). On Mastodon both are the home feed, so a post there can be both events.

Events per platform

GET /v1/platforms lists them for each platform as alert_events.

Read events

GET/v1/workspaces/{workspace_id}/alert-events

The query takes alert_id, account_id, kind,limit (1 to 200, default 50), and either cursor or afterwith wait. The answer is { events, next_cursor, last_event_id }. Events are kept 90 days.

List

No after and no wait. Newest first. next_cursor is the cursor of the next, older page, else null.last_event_id is null.

Long poll

after, wait or both. Oldest first: the events recorded after the event after, or from the oldest kept when there is no after. When there are any, the answer comes at once; else it waits up to wait seconds (0 to 60, default 0) for the next one. next_cursor isnull.

In a long poll, last_event_id is the last event of the answer, elseafter. Send it as after in the next request. Events come in the order BuzzTake recorded them, so an agent that always does this gets each event once and misses none.

curl -H "Authorization: Bearer $BUZZTAKE_API_KEY" \
  "https://api.buzztake.com/v1/workspaces/$WORKSPACE_ID/alert-events?after=$LAST_EVENT_ID&wait=60"

{
  "events": [{ "id": "0199c7d8-...", "kind": "like", "actor": "alice", ... }],
  "next_cursor": null,
  "last_event_id": "0199c7d8-..."
}

cursor with after or wait is422 invalid_input. An unknown cursor, after oralert_id is a 404. An after goes away with its alert or after 90 days: list again to start over.

One alert's events

GET/v1/alerts/{id}/events

The same query, without alert_id, and the same answer, for the events of one alert.

MCP

The alert tools are list_alerts, create_alert,update_alert, delete_alert, list_alert_events andwait_for_alert_events. wait_for_alert_events is the long poll:workspace_id, an optional alert_id, after, andwait (default 30, at most 60). It returns the events and thelast_event_id for the next call. Every MCP client can use it.

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "wait_for_alert_events",
    "arguments": { "workspace_id": "0199...", "after": "0199c7d8-...", "wait": 60 }
  }
}

Each alert is also the resource buzztake://alerts/{alert_id}/events. A read gives its newest events. The server declares resources.subscribe. Afterresources/subscribe, the session's GET /mcp stream getsnotifications/resources/updated with that URI once for each batch of new events. The client then reads the resource.

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "resources/subscribe",
  "params": { "uri": "buzztake://alerts/0199e5f6-.../events" }
}

{
  "jsonrpc": "2.0",
  "method": "notifications/resources/updated",
  "params": { "uri": "buzztake://alerts/0199e5f6-.../events" }
}

• Over HTTP, a session can subscribe to at most 10 alert resources, and to no other resource.
• The stream request carries the API key like every other request. The server follows the subscribed alerts only while a stream is open, and goes on from where the last stream stopped.
• resources/unsubscribe, DELETE /mcp or the end of the session stops the updates. When the alert is deleted, the server sends one last update and stops.

Rules

• A check is one browser visit to one account. It reads the notifications, the conversations and the timelines that the account's alerts want events from. An account in more than one alert is checked once for all of them, at the shortest interval. An account that is notactive is not checked until it is active again.
• New means not seen on this account before. A message is a conversation that is new or changed and whose last message is not from the account. The account's own posts are not events. An item the page dates more than 10 minutes before the previous check is old and gives no event. timeline_post has no such rule: the home feed shows older posts that are new to the user.
• A check never waits for a person. When a page asks a question first, such as the X Chat passcode, the check leaves that read out and lists its events as unread_kinds. A check that can read nothing fails and costs nothing. Answer the question once, in aread_conversation action or the live browser.
• The first check after you create or resume an alert records what is there and gives no events. A new account or a new event gets its own first check of this kind.
• A check the balance cannot pay pauses every alert on that account, withpause_reason: insufficient_credits. A paused alert records nothing. Top up, then send PATCH {"status": "active"}.
• With webhook: true, each event goes as one alert.triggered event to each active workspace webhook that subscribes to it. Its data hasalert_id, event_id, account_id,platform, kind, actor, actor_id,text, url and occurred_at.
• An API key needs inbox_read in the workspace.

Cost

A check is one browser visit to one account. It costs 2 credits (alert_check) when it succeeds. An account in more than one alert is checked once, at the shortest interval, so these figures are the most one account can cost.

Routes

Alert event

{
  "id": "0199c7d8-...",
  "alert_id": "0199e5f6-...",
  "account_id": "0199a1b2-...",
  "platform": "x",
  "kind": "like",
  "actor": "alice",
  "actor_id": "1234567890",
  "text": "Alice liked your post",
  "url": "https://x.com/acme_demo/status/1",
  "occurred_at": "2026-10-13T19:58:00Z",
  "created_at": "2026-10-13T20:00:04Z"
}

actor, actor_id, text, url andoccurred_at are what the page shows, or null.actor_id is the actor's account id on the platform, which stays when the handle changes; a message has none. For a post, actor is its author's handle andurl the post. A client ignores members it does not know.