AntsData
开发者文档

X (Twitter) Scraper：账号资料与推文采集

采集为异步**：提交 run → 轮询 → 取数。端到端流程见 快速开始；统一响应信封、run 状态机、计费与错误处理见 认证与错误处理。本页只列 X 两个端点的 target 字段与输出字段。

快速说明

  • Base URL：https://api.antsdata.com/v1
  • 方法与路径：提交 run 为 POST /v1/scraper/x/<资源>；轮询与取数走通用的 GET /v1/scraper/runs/{id} 系列（见快速开始）。
  • 鉴权：请求头 Authorization: Bearer ants_xxx（静态 API Key）。
  • Content-Type：application/json
  • 提交体：统一为 { "deliveryMode": "async", "recordLimit": <每目标记录上限>, "targets": [ ... ] }；targets[] 每个元素的字段见下方各端点。

💡 也可用 deliveryMode: "sync" 同步模式（小任务阻塞等终态，超时自动 fallback 转轮询）——详见 快速开始 · 同步模式。

  • 计费：按成功产出的数据条数结算，失败目标释放不计费，细节见 认证与错误处理。

端点一览

端点 说明 target 关键字段
POST /v1/scraper/x/profile 账号资料 username
POST /v1/scraper/x/posts 账号推文 username、maxResults

Profile — 账号资料

采集 X 账号的公开资料。

target 字段（targets[] 每个元素）：

字段 类型 必填 说明
username string ✅ X 用户名（不带 @）

输出字段（records 每条记录）：

字段 类型 说明
username string 用户名（唯一标识）
displayName string 显示名称
bio string 个人简介
location string 地理位置
websiteUrl string 外链网址
followersCount number 粉丝数
followingCount number 关注数
postsCount number 发帖总数
likesCount number 获赞总数（如可获取）
isVerified boolean 是否蓝 V / 认证
isPrivate boolean 是否为私密账号
createdAt string 账号注册时间
profileImageUrl string 头像 URL
bannerImageUrl string 封面图 URL
profileUrl string 主页链接

提交示例：

curl -X POST "https://api.antsdata.com/v1/scraper/x/profile" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "username": "jack" },
      { "username": "elonmusk" }
    ]
  }'

提交后返回 HTTP 201，data 内含任务号 id 与 status: "queued"；随后按快速开始轮询 GET /v1/scraper/runs/{id} 到 succeeded，再取记录。

Posts — 账号推文

采集指定账号发布的推文列表。

target 字段（targets[] 每个元素）：

字段 类型 必填 说明
username string ✅ X 用户名（不带 @）
maxResults number — 该账号返回推文数上限（与 run 级 recordLimit 取更小者）

输出字段（records 每条记录）：

字段 类型 说明
id string 推文 ID
url string 推文链接
text string 推文文本内容
createdAt string 发布时间
author object 作者信息
author.username string 作者用户名
author.displayName string 作者显示名
author.profileUrl string 作者主页
metrics object 互动指标
metrics.likeCount number 点赞数
metrics.retweetCount number 转推数
metrics.replyCount number 回复数
metrics.quoteCount number 引用推文数
metrics.impressionCount number 浏览量
entities object 正文提取的实体
entities.hashtags array 标签列表
entities.mentions array @提及用户名列表
entities.urls array 链接列表
entities.urls.expandedUrl string 展开后的完整 URL
entities.urls.displayUrl string 页面显示的短 URL
media array 媒体列表
media.type string photo / video / gif
media.url string 媒体直链
media.previewUrl string 缩略图 URL
media.altText string 图片替代文本
isReply boolean 是否为回复
isRetweet boolean 是否为转推
isQuoteTweet boolean 是否为引用推文
quotedTweet object 引用的推文（存在时）
quotedTweet.id string 原推文 ID
quotedTweet.text string 原推文内容
quotedTweet.authorUsername string 原作者用户名
lang string 语言代码

提交示例：

curl -X POST "https://api.antsdata.com/v1/scraper/x/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 200,
    "targets": [
      { "username": "elonmusk", "maxResults": 100 }
    ]
  }'

提交后返回 HTTP 201，data.id 为任务号、status: "queued"；按快速开始轮询取数。

取数

run 进入 succeeded 后，按任务号取记录或下载（每条记录形状即上文"输出字段"）：

  • 分页记录：GET /v1/scraper/runs/{id}/records?page=1&pageSize=20
  • 下载产物：GET /v1/scraper/runs/{id}/download?format=json|csv|excel

完整轮询与取数示例见 快速开始。

下一步

FAQ

Q: 为什么提交后没有直接返回资料 / 推文数据？

采集是异步的：提交拿任务 id，后台执行，轮询到 succeeded 后再按 id 取记录。详见快速开始。

Q: 一次能采集多个账号吗？

可以。targets 是数组，一个 run 可含多个账号，内部并行执行，逐账号状态见 run 对象的 tasks[]。

Q: 用户名要带 @ 吗？

不带。直接传 handle（如 elonmusk）即可。

Q: 私密或不存在的账号会怎样？

该目标在 tasks[] 里以 status: "failed" + errorMessage 体现，其余目标仍可成功（部分成功照常出数）；失败目标释放不计费。