# Auto Data — 数据采集 API（供 AI agent 调用）

Auto Data 是数据采集平台：提交采集任务拿 task_id，轮询到终态读原始记录。采集异步，
result 是原始数据；富化字段（打标/向量）随后经查询 API 补齐。

## 鉴权
每次请求带：Authorization: Bearer <token>   或   X-API-Key: <token>
令牌由平台运营签发，按中台身份校验；未知/过期/空 → 401 unauthorized。
代扣：用服务 key 替终端用户跑任务时，每个请求（提交和轮询都要）带
X-On-Behalf-Of: <用户身份>，预扣/结算/用量记到该用户名下；漏带则全记在 key 所有者名下。

## 契约：submit -> poll
提交返回 { "task_id": "tq_9f3c...", "status": "queued" }；task_id 是不可猜字符串，原样保存。
非 2xx：401 令牌无效 / 429 admission 满 (retry_after) / 402 Mia Points 不足 / 400 字段缺失。
提交幂等（同平台+同客户+同关键词的在途任务返回既有 task_id）。
轮询 GET /api/v1/serving/crawl/{task_id}：status ∈ queued|running|success|failed|timeout|cancelled。
queued≈5s / running≈3s 按 retry_after 再轮询，勿死循环。轮询/取消都校验归属，须用提交时的
同一凭证（含同一 X-On-Behalf-Of）：缺凭证 401、非本人/不存在 404。
success → result 是对象 { "count": N, "items": [...] }，记录在 result.items（不是裸数组）。
取消仅 queued：DELETE /api/v1/serving/crawl/{task_id}。

## 字段命名已统一（旧名仍作别名受理）
limit（旧 count/posts_limit/ads_limit）· keyword（旧 query）· handle（旧 username）·
comments_limit（旧布尔 with_comments）· company_id/start_date/end_date（旧 companyId 等）。

## 提交端点（* 必填，其余为默认值）
- 小红书 搜索:      POST /api/v1/serving/crawl            {"platform":"rednote","keyword"*:"护肤","limit":20,"time_range":"1week","skip_existing":false}
- 小红书 用户主页:  POST /api/v1/serving/rednote/account  {"handle"* | "user_id"*,"limit":20,"comments_limit":0,"skip_existing":false}
    · time_range(仅 rednote): 1day/1week/6months/all(走 XHS 时间筛选卡) 或 custom + time_range_start/time_range_end(YYYY-MM-DD, 精确日期区间, 含端点)
    · skip_existing:true = 增量采集, 滚动中实时查库去重、只回未采过的新帖(搜索/主页均可; 多次采集同一目标不重复翻页)
- Threads 搜索:     POST /api/v1/serving/threads/search   {"keyword"*:"AI"}
- Threads 主页:     POST /api/v1/serving/threads/account  {"handle"*:"zuck"}  (不带 @)
- Twitter/X 主页:   POST /api/v1/serving/twitter/account  {"handle"*:"elonmusk","limit":20}  (不带 @)
- Reddit 子版:      POST /api/v1/serving/reddit/subreddit {"subreddit"*:"AskReddit","limit":20,"sort":"hot","with_comments":false}  (区分大小写，不带 r/)
- Reddit 搜索:      POST /api/v1/serving/reddit/search    {"query"*:"python","limit":20,"subreddit":?,"with_comments":false}
- Reddit 单帖:      POST /api/v1/serving/reddit/post      {"url"*:"https://www.reddit.com/r/.../comments/..."}  (含评论树)
- Facebook:         POST /api/v1/serving/facebook/account {"url"*:"https://www.facebook.com/nike","limit":20}
- Facebook 广告库:  POST /api/v1/serving/facebook/ads/search  {"query"*:"nike","limit":50}
- Instagram:        POST /api/v1/serving/instagram/account    {"handle"*:"nike","limit":20}
- LinkedIn:         POST /api/v1/serving/linkedin/account     {"url"*:...} 或 {"handle"*,"type"*:"person|company"}
- LinkedIn 广告库:  POST /api/v1/serving/linkedin/ads         {company | keyword | company_id 三选一*}
- TikTok 广告库:    POST /api/v1/serving/tiktok/ads           {"region":"US","period":30,"limit":50}
- Google 广告库:    POST /api/v1/serving/google/ads           {domain | company_name | advertiser_id 三选一*}

## 记录字段（result.items 每条）
公共信封：biz_key / url / title / content / author / published_at / metrics（metrics 键随平台不同，按样本读）。
extras：源特有字段包。其中——
- 图片/视频：ig/facebook/twitter/threads/linkedin/reddit 帖子带 extras.media = [{type:"image"|"video",url,thumbnail}]
  + extras.cover_image（单张封面）。纯文字帖 media 为空列表；LinkedIn 公司帖上游无媒体，
  个人帖需 with_post_content:true 才带。Reddit 文字正文在 content（self 帖）；评论在
  extras.comments（/reddit/post 或 with_comments:true）；listing 场景下图片直链常因上游裁剪为空。
- RedNote 不用 media，用 extras.images / cover_url / video_url。
- author：顶层为归一展示名（字符串）；结构化字段（user_id/粉丝数/地区）在 extras.author。

## 读富化记录（跨任务浏览，非按任务过滤）
- 精确单条:  GET /api/serving/record/{connector_id}/{biz_key}   (404 = 富化未完成，稍后重试)
- 浏览某源:  GET /api/serving/records?connector_id=<id>&limit=50&offset=0
connector_id: rednote_search, threads_api, twitter_api, reddit_api, facebook_api, facebook_ad_library,
instagram_api, linkedin_api, tiktok_api, google_ad_library

## 易错点
- Facebook 目标要完整主页 URL 或精确 handle（猜词会 404）。
- Threads/Twitter handle 去掉 @。
- Reddit subreddit 区分大小写、不带 r/；要评论用 /reddit/post 或 with_comments:true。
- LinkedIn handle 要配 type，或传完整 URL 由 /in/ vs /company/ 推断。
- 广告库“三选一”一个都不给 → 400。
- 按用量计费扣 Mia Points，别循环请求超大 limit。
- RedNote 走无头浏览器，可能 1-2 分钟，给足轮询上限。