Skip to docs content
Docs

Tracked accounts

Tracked accounts define what the live feed and History API can return. Add them in the dashboard or operate them from your own backend.

Add and remove accounts

The `accounts` field accepts one string or an array of strings. Handles are normalized, so callers may send `marketdesk` or `@marketdesk`.

Add accountstypescript
const response = await fetch("https://api.tweetstream.io/api/add-account", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    accounts: ["marketdesk", "realDonaldTrump"],
  }),
});
 
console.log(await response.json());
 
Remove accounttypescript
const response = await fetch("https://api.tweetstream.io/api/remove-account", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    accounts: "marketdesk",
  }),
});
 
console.log(await response.json());
 
Resultjson
{
  "action": "follow",
  "requestId": "8b4f9c9c-9e7b-4a0c-9c7d-2d4d6f0a9a25",
  "error": null,
  "results": [
    {
      "input": "marketdesk",
      "handle": "marketdesk",
      "normalizedHandle": "marketdesk",
      "state": "added"
    },
    {
      "input": "realDonaldTrump",
      "handle": "realDonaldTrump",
      "normalizedHandle": "realDonaldTrump",
      "state": "added"
    }
  ]
}
 

Read current usage

`/api/me` returns your plan, tracked-account usage, active WebSocket usage, and subscription status. It is private and no-store.

FieldTypeNotes
planBASIC, ELITE, or ENTERPRISERuntime plan enum
trackedAccountsobjectCount, limit, and normalized handles
websocketobjectCurrent active connection count and plan limit
stripeobjectSubscription status and billing period fields; identifiers should be treated as private
Requesttypescript
const response = await fetch("https://api.tweetstream.io/api/me", {
  headers: {
    Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`,
  },
});
 
console.log(await response.json());
 
Responsejson
{
  "plan": "ELITE",
  "trackedAccounts": {
    "count": 2,
    "limit": 250,
    "handles": ["marketdesk", "realDonaldTrump"]
  },
  "websocket": {
    "count": 1,
    "limit": 10
  },
  "stripe": {
    "subscriptionStatus": "ACTIVE",
    "customerId": "[redacted]",
    "hasCustomer": true,
    "subscriptionId": "[redacted]",
    "currentPeriodStart": "2026-06-30T00:00:00.000Z",
    "currentPeriodEnd": "2026-07-30T00:00:00.000Z",
    "canceledAt": null
  }
}
 

Handle result states

StateWhen it appearsRecommended handling
addedHandle was added to the watchlistTreat as success
already_followingHandle is already trackedTreat as idempotent at the row level
removedHandle was removedTreat as success
not_followingHandle was not trackedTreat as idempotent at the row level
invalid_input, duplicate, not_found, failedInput or sync problemShow the row-level message and retry only when appropriate

REST status codes

Add and remove endpoints return row-level results. HTTP status reflects the batch outcome, while each result row tells you what happened to that handle.

StatusWhen it appearsNotes
200Every row completed with a direct add or removeAll rows are straightforward successes
207Some rows completed and some rows failed or were already in the requested stateRead each results row before retrying
400The request body is invalid or no row changed statealready_following and not_following can appear here when the whole batch was idempotent

Plan limits

  • Minimum: 50 monitored accounts and 3 WebSocket connections after trial.
  • Trial: 5 monitored accounts and 1 WebSocket connection for 3 days.
  • Pro: 250 monitored accounts and 10 WebSocket connections.
  • Scale: self-serve higher monitored-account and WebSocket limits from the pricing page.
  • History replay is available on Pro and Scale.