每分钟轮询一次账号,是知道“有新内容”最贵的方式。监控把这件事反过来:你只需声明账号和过滤条件,API 会把命中的推文推送到你的 webhook。
创建监控
curl -X POST 'https://api.skilltweet.com/v1/monitors' \
-H 'X-API-KEY: $AGENTTWEET_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"username": "openai",
"keywords": ["api", "launch"],
"webhook_url": "https://example.com/hooks/x",
"interval_minutes": 5
}'| 字段 | 约束 |
|---|---|
username | 要监控的 X 账号,1–15 个字符,不带 @ |
keywords | 可选过滤词,最多 10 个、每个 1–24 字符;留空表示所有推文 |
webhook_url | 命中推文的投递地址;可选,不填也能创建监控 |
interval_minutes | 轮询间隔,1 到 1,440 分钟,默认 5 |
监控归属于当前 API key:GET /v1/monitors 查看列表,DELETE /v1/monitors/:id 删除一条。
你的接口会收到什么
命中的新推文以 JSON POST 投递,content-type: application/json,User-Agent 为 AgentTweet-Monitor/1.0:
{
"event": "tweet.new",
"monitor_id": "…",
"username": "openai",
"delivered_at": "2026-11-10T09:15:00.000Z",
"tweets": [
{ "id": "…", "text": "…", "author": "…" }
]
}写处理逻辑之前,有两个细节值得知道:
- 首次轮询不会触发 webhook。 否则创建监控的瞬间,账号最近的全部历史会一次性砸过来。投递从第二次轮询开始,只包含期间出现的新推文。
- 投递是尽力而为,超时 10 秒。 尽快返回 2xx 再异步处理;接口慢或宕机的那一轮会记为投递失败,而不是无限重试。
tweets 里的推文和 /v1/tweets/search 返回的扁平 JSON 完全一致,一套处理逻辑就能同时覆盖两条链路。
不写代码也能过滤
keywords 在服务端匹配,所以一个高产账号挂三个关键词,成本和不挂一样,你的接口只在真正有内容时才被唤醒。如果你更想按自己的节奏拉取,就让 webhook_url 留空——GET /v1/monitors 加时间线接口同样能用。
接下来看什么
- Token 计费与充值档位:普通 API 调用怎么扣费。
- 完成第一次请求:所有接口共用的响应结构。
- API 文档:监控接口的完整说明,包含投递记录。