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 handle or an array of handles. You can include or omit the leading @; handles are matched case-insensitively. A standard API key updates the standard tracked-account list; an active Ultra API key updates the Ultra selection and enforces its paid account limit.

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",
      "state": "added"
    },
    {
      "input": "realDonaldTrump",
      "state": "added"
    }
  ],
  "summary": {
    "failed": 0,
    "succeeded": 2,
    "total": 2
  }
}

Read current usage

`/api/me` accepts either the standard or Ultra API key and returns base-plan usage plus additive Ultra Speed details. It is private and no-store.

FieldTypeNotes
credentialScopestandard or ultra_speedScope of the bearer key used
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
ultraSpeedobject or nullUltra status, billing cycle, limits, scoped WebSocket usage, and cancellation timing
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
{
  "credentialScope": "standard",
  "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
  },
  "ultraSpeed": {
    "active": true,
    "status": "ACTIVE",
    "billingCycle": "MONTHLY",
    "paymentRail": "STRIPE_CARD",
    "accountLimit": 25,
    "websocket": {
      "count": 1,
      "limit": 5
    },
    "currentPeriodEnd": "2026-07-30T00:00:00.000Z",
    "cancelAtPeriodEnd": false,
    "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
200No row failed, including idempotent success rowssummary.failed is 0; already_following and not_following are successful outcomes
207Some rows succeeded and some rows failedRead each results row before retrying
400The request body is invalid or every row failed for a non-temporary reasonFix the request or row-level errors before retrying
503Every row failed for a temporary reasonRetry the batch with backoff

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.