跳到文档正文
文档

管理 X/Twitter 监控账号和实时提醒

监控账号决定实时发送范围，也决定 History API 可以返回哪些已存内容、资料、关注和关联账号事件。你可以在控制台或自己的后端管理这些账号。

添加和移除账号

accounts 字段接受一个 handle 或 handle 数组。开头的 @ 可以省略，handle 匹配不区分大小写。标准 API key 会更新标准监控账号列表；有效的 Ultra API key 会更新 Ultra 选择并执行其已付费账号上限。

添加账号typescript
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());
移除账号typescript
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());
结果json
{
  "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
  }
}

读取当前用量

`/api/me` 接受标准或 Ultra API key。它会返回基础套餐用量和附加的 Ultra Speed 详情。响应为私有且不缓存。

字段类型说明
credentialScopestandard 或 ultra_speed本次 Bearer key 的权限范围
planBASIC、ELITE 或 ENTERPRISE运行时套餐枚举
trackedAccountsobject数量、限制和规范化 handles
websocketobject当前活跃连接数和套餐限制
stripeobject订阅状态和账期字段；标识符应视为私有
ultraSpeedobject 或 nullUltra 状态、账期、限制、独立 WebSocket 用量和取消时间
请求typescript
const response = await fetch("https://api.tweetstream.io/api/me", {
  headers: {
    Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`,
  },
});
 
console.log(await response.json());
响应json
{
  "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
  }
}

关联账号列表变更

有效或试用中的 Pro、Scale 和 Ultra 套餐可为已监控的企业账号启用关联账号列表变更，此功能默认关闭。调用 `POST /api/affiliate-alerts` 开启，调用 `DELETE /api/affiliate-alerts` 关闭，也可以使用控制台。将已监控的 handle 作为 `account` 发送，开头的 @ 可以省略。重复发送相同请求是安全的。成功时返回 `{ account, affiliateAlertsEnabled }`。开启提醒时，TweetStream 会检查账号是否仍符合企业账号资格；否则，API 会返回 `400` 和 `{ error: "This account is not a business account." }`。TweetStream 检测到变化后，会通过 WebSocket、控制台实时流和 Discord 通知路由发送事件。使用 `GET /api/history?type=affiliate` 回放已记录的变化。关键词过滤不适用。请用 `(organization.id, member.id)` 保存关系，`eventId` 仅用于完全相同的重放去重。不提供当前列表快照或功能上线前回补。

状态出现时机处理方式
200已保存的设置与请求一致读取 affiliateAlertsEnabled
400请求 body 无效或账号不是企业账号修正请求
401Bearer key 缺失或无效发送有效的 API key
403订阅或功能权限未生效检查套餐权限
404此 API key 未监控该 handle检查已监控 handle
500TweetStream 无法确认资格稍后重试
启用或关闭关联账号提醒typescript
async function setAffiliateAlerts(account: string, enabled: boolean) {
  const response = await fetch("https://api.tweetstream.io/api/affiliate-alerts", {
    method: enabled ? "POST" : "DELETE",
    headers: {
      Authorization: `Bearer ${process.env.TWEETSTREAM_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ account }),
  });
 
  if (!response.ok) {
    throw new Error(await response.text());
  }
  return await response.json();
}
 
console.log(await setAffiliateAlerts("marketdesk", true));
console.log(await setAffiliateAlerts("marketdesk", false));

账号处理结果

状态出现时机推荐处理
added账号已加入监控列表视为成功
already_following账号已经在监控中作为逐行幂等结果处理
removed账号已移除视为成功
not_following账号原本没有被监控作为逐行幂等结果处理
invalid_input, duplicate, not_found, failed输入无效、输入重复、账号不存在或操作失败展示逐行 message，仅在合适时重试

REST 状态码

Add 和 remove 端点会为每个 handle 返回一行结果。HTTP 状态说明批处理的整体结果，每一行 result 则说明对应 handle 发生了什么。

状态出现时机说明
200没有任何行失败，包括幂等成功结果summary.failed 为 0；already_following 和 not_following 都属于成功结果
207部分行成功，部分行失败重试前读取 results 和 summary
400请求 body 无效，或每一行都因非临时原因失败重试前先修正请求或逐行错误
503每一行都因临时原因失败使用退避策略重试整批请求

套餐限制

  • Minimum：试用后 50 个监控账号和 3 个 WebSocket 连接。
  • Trial：3 天内 5 个监控账号和 1 个 WebSocket 连接。
  • Pro：250 个监控账号和 10 个 WebSocket 连接。
  • Scale：可在定价页自助配置更高的监控账号和 WebSocket 限制。
  • Pro 和 Scale 提供 History 回放；Ultra 提供 affiliate 回放。