AlphaGrow API 客户使用指南

日期：2026-09-21
服务地址：https://alphagrow.aivontek.dev
API 路径前缀：/v1/customer

本文面向客户技术团队，介绍数据查询、更新、服务请求、结果下载及自动更新池的接入方法。示例使用接口约定的真实字段和响应形态；凭据、业务 ID、账号及数值为示例，不代表实际业务结果。响应示例仅展示业务接入所需字段，不表示完整响应；客户端应容忍额外字段，但不要将整个响应原样回写。

TikTok / YouTube 数据接口需已开通对应平台权限后使用。 请先确认账户授权，并通过能力查询接口判断可用操作；本文提供接口用法，不表示所有客户均已开通。

目录

1. 选择业务接口
2. 快速开始
3. 鉴权与权限
4. 通用数据约定
5. 接口总表
6. Instagram 数据基线与更新
7. 服务请求与账号配置需求
8. Instagram 数据任务与文件下载
9. Instagram 自动更新池
10. Instagram 当前数据与每日快照
11. TikTok / YouTube 数据接口
12. 幂等、版本、限流与重试
13. 错误处理

1. 选择业务接口

数据基线、服务工单和数据任务是不同对象：创建基线不等于提交工单，创建工单也不自动创建文件任务。请分别保存各自 ID。

Instagram 数据接口仅接受 Instagram 链接；TikTok / YouTube 使用第11章接口。两类服务请求可指定平台，详见第7章。账号配置需求只需提供内容领域、地区、语言、形式及粉丝区间等匹配偏好，不要提交账号密码、验证码、登录会话或账号控制权资料。

2. 快速开始

1. 向服务方取得客户 API Key，确认有效期、请求额度及所需平台与池权限。
2. 将 Key 保存在客户服务端密钥管理系统中。不要放入网页、移动端安装包、公开代码库或 URL。
3. 由客户服务端调用 API，网页和移动端经自己的后端访问；不要假定支持任意网页跨域直连。
4. 下列地址为业务服务地址，写入请求会创建业务记录。调用前确认客户身份及目标数据。

以下假设已安全设置 ALPHAGROW_API_KEY：

BASE_URL='https://alphagrow.aivontek.dev'
curl --fail-with-body --silent --show-error \
  "$BASE_URL/v1/customer/service-orders" \
  -H "Authorization: Bearer $ALPHAGROW_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"targets":["https://www.instagram.com/example/"],"refresh_latest":false}'

该请求创建数据基线并返回已有数据。保存 service_order_id，后续查询使用 GET，避免重复创建。

需幂等键的写请求务必保存原键及正文。refresh_latest 表示是否请求更新；使用已有数据时，应展示结果时间，不将其当作当前时间。

3. 鉴权与权限

3.1 客户 API Key

所有第 5 节列出的 API 都使用：

Authorization: Bearer agk_YOUR_API_KEY
Accept: application/json

JSON 写请求另带 Content-Type: application/json。API Key 缺失、格式非法、过期、撤销，或客户暂停，均可能返回 401 UNAUTHORIZED。更换 Key 后仍属于原客户身份；不能靠换 Key 绕过客户级限流。

Key 由服务方签发或轮换，客户 API 没有自助签发接口。不要在 URL 查询参数、业务正文、错误日志、工单截图或分析埋点中传递 Key。

3.2 网页访问码不是 API Key

agc_... 用于客户网页登录，兑换安全 Cookie；不能作为 /v1/customer/* 的 Bearer Token。agk_... 也不能当网页登录访问码。本文 API 使用 Bearer 鉴权，不使用网页登录 Cookie。

3.3 权限模型

API Key 从认证信息确定客户范围，客户端不要自行提交 customer_id 选择其他客户。

账号池有三项客户级权限，需由服务方开放：

网页登录权限不代替 API Key 的客户权限。

文件下载须具备对应结果的访问权限。

3.4 对象归属

基线、工单、数据任务、文件及账号池均按已认证客户限定范围。权限检查通过后，不存在或属于其他客户的对象通常返回对应的 404；若客户级权限关闭，也可能先返回 403。不得把 403/404 用作枚举其他客户资源的手段。

只处理当前客户获授权的对象，不依赖本文未定义的响应字段。

4. 通用数据约定

4.1 四指标与未知值

• 0 是有效数值，不能显示成“未知”。
• null 表示未知或对当前对象不适用，不能转成零。
• 既有 Instagram 接口兼容差异：基线缓存完全缺失时，指标键可能直接缺省；客户需要把“缺省或 null”显示为未知，并结合 cache_state、refresh_state 判断原因。既有接口并非每个指标都有独立原因码；social 的四指标均为带 reason 的对象，见第11章。
• 主页的播放、点赞、评论不是主页级累计指标。池数据/日报中这三项为 null，不能当作 0。
• 请求和响应统一使用本表指标字段。

JavaScript 展示示例：

const displayMetric = value => value == null ? '未知' : String(value);
// displayMetric(0) === '0'；不要用 value || '未知'。

4.2 时间

一般时间字段是 UTC ISO 8601 字符串，例如 2026-09-21T06:00:00.000Z，没有结果时可能为 null。池和日报的业务时区为 Asia/Shanghai；任务月度额度以 UTC 自然月计算。

兼容注意：工单部分期限字段可能返回 YYYY-MM-DD HH:mm:ss 的 UTC 字符串。解析时明确按 UTC 处理，不要依赖浏览器本地时区。既有 Instagram 接口没有统一的每指标独立更新时间协议：基线用 updated_at，池/日报用 metrics_at，不能从单一时间声称所有指标都同时更新。social 则每个指标独立返回 fetched_at，详见第11章。

4.3 ID 与响应形态

• ID 是不透明字符串，仅保存和回传，不解析其格式或自行生成。
• 请求与响应没有统一 {code,data} 包装；以每个接口示例为准。
• 成功工单响应的 request_id 是业务工单 ID；错误响应的同名字段通常是请求追踪 ID。客户应用应分别保存为 serviceRequestId 和 traceId。
• 可以发送最多 128 字符的 X-Request-Id 辅助排查，但不是幂等键，也不保证每个接口都回显。
• 容忍响应增加字段，但不要将整个响应原样回写；工单创建严格拒绝未知字段。
• 本文标为“节选”的响应仅展示所需字段；不是完整对象，也不承诺省略字段不存在。

4.4 链接输入

以下规则适用于既有 Instagram 数据接口；social 平台URL规则见第11章，服务请求links按所选platform验证。提交 HTTPS 的 instagram.com 或 www.instagram.com 公开主页、/reel/、/reels/、/p/、/tv/ 链接。不传登录链接、私密凭据或追踪参数。建议先规范化并去重，保留自己业务中的输入映射。

不同接口的重复策略不同：基线和池会按目标去重；工单和 jobs 拒绝规范化后的重复链接。当前基线/池的重复输入与返回原始链接映射仍有兼容限制，客户端预先去重可避免歧义。

5. 接口总表

以下均使用客户 API Key；幂等键与版本要求详见第12章。TikTok / YouTube 接口需已开通对应平台权限。

共 35 个方法/路径组合：Instagram 数据及通用服务接口22个，TikTok / YouTube 数据接口13个。GET 与 HEAD 分别计数；两类服务请求共用一个创建接口。

6. Instagram 数据基线与更新

6.1 创建基线

POST /v1/customer/service-orders

本接口只接受表中字段；不接受 include_recent_videos，即使值为 false 也会被拒绝。

{
  "targets": ["https://www.instagram.com/example/"],
  "refresh_latest": false
}

有主页缓存时，创建成功响应示例（HTTP 201）：

{
  "service_order_id": "serviceorder_11111111111111111111111111111111",
  "baseline_query_id": "dataquery_22222222222222222222222222222222",
  "refresh_latest": false,
  "baseline_state": "READY",
  "duplicate_count": 0,
  "items": [
    {
      "ordinal": 0,
      "input": "https://www.instagram.com/example/",
      "kind": "PROFILE",
      "canonical_key": "example",
      "cache_state": "HIT",
      "followers": 12500,
      "updated_at": "2026-09-21T06:00:00.000Z",
      "refresh_state": "NOT_REQUESTED"
    }
  ],
  "request_id": "trace-baseline-example"
}

缓存完全缺失时，单项可能是以下结构；客户端不要假设一定存在 followers 键：

{
  "ordinal": 0,
  "input": "https://www.instagram.com/example/",
  "kind": "PROFILE",
  "canonical_key": "example",
  "cache_state": "CACHE_MISS",
  "updated_at": null,
  "refresh_state": "NOT_REQUESTED"
}

MEDIA 的已缓存指标形态（单项节选）：

{
  "kind": "MEDIA",
  "canonical_key": "ABC123xyz",
  "cache_state": "HIT",
  "plays": 85000,
  "likes": 0,
  "comments": 120,
  "owner_user_id": "1234567890",
  "updated_at": "2026-09-21T06:05:00.000Z"
}

owner_user_id 是公开媒体所属账号标识，不是客户身份。当前媒体基线不直接合并所属主页粉丝字段；如需组合四指标，使用已授权池的当前数据或日报，不能自行补造基线响应。

6.2 刷新行为与状态

• false：读取已有数据，仍创建基线记录；数据缺失时显示未知。
• true：请求更新；返回结果可能为5分钟内的完整已有数据。请以返回的更新时间和逐项状态为准，不代表同步返回最新值，也不代表重复 POST 会返回同一基线。
• 无法解析账号身份的主页可能返回 UNRESOLVED_IDENTITY；不能保证每个陌生主页都能立即刷新。
• 更新尚未完成时通常返回 202、baseline_state:"REFRESHING"；没有待刷新项时返回 201、baseline_state:"READY"。
• READY 表示本次基线对象可读，不是每个指标已知、已更新或服务已完成的保证。

6.3 读取基线

GET /v1/customer/service-orders/{service_order_id}

成功 200，以下为响应节选：

{
  "service_order_id": "serviceorder_11111111111111111111111111111111",
  "state": "BASELINE_READY",
  "input_count": 1,
  "created_at": "2026-09-21T06:10:00.000Z",
  "updated_at": "2026-09-21T06:10:00.000Z",
  "baseline": {
    "baseline_query_id": "dataquery_22222222222222222222222222222222",
    "refresh_latest": false,
    "state": "HISTORY_READY",
    "items": [
      {
        "ordinal": 0,
        "input": "https://www.instagram.com/example/",
        "kind": "PROFILE",
        "canonical_key": "example",
        "cache_state": "HIT",
        "followers": 12500,
        "updated_at": "2026-09-21T06:00:00.000Z",
        "refresh_state": "NOT_REQUESTED"
      }
    ]
  },
  "request_id": "trace-baseline-read"
}

顶层 state 可为 BASELINE_READY、BASELINE_REFRESHING、READY_FOR_FULFILLMENT；baseline.state 可为 HISTORY_READY、REFRESH_QUEUED、SUCCEEDED、PARTIAL_SUCCEEDED。POST 的 baseline_state 与 GET 的这两层状态不是同一枚举，不能直接混用。baseline 没有记录时可能为 null。

不存在或不属于当前客户时为 404 SERVICE_ORDER_NOT_FOUND。当前没有基线列表、取消或修改接口。POST 没有持久幂等，超时后不要无条件重发；优先使用已取得的 ID 查询。

7. 服务请求与账号配置需求

7.1 创建 AlphaGrow 工单

POST /v1/customer/requests，必须带 Idempotency-Key。

{
  "request_type": "METRIC_TARGET",
  "links": ["https://www.instagram.com/example/"],
  "target_followers": 10000,
  "target_plays": 0,
  "target_likes": 0,
  "target_comments": 0,
  "note": "请评估公开主页的目标需求"
}

这些数值表达客户需求目标，不构成自动报价、可交付性或效果承诺。当前请求是一组链接加一组目标，没有逐链接独立目标数组；需要不同目标时提交不同请求。字段值为 0 不等于未知，是否代表不要求该指标应在业务确认时明确。

HTTP 201 创建响应示例：

{
  "request_id": "request_33333333333333333333333333333333",
  "request_type": "METRIC_TARGET",
  "title": "公开账号指标需求 · 1 个链接",
  "status": "RECEIVED",
  "status_version": 1,
  "received_at": "2026-09-21T06:20:00.000Z",
  "created_at": "2026-09-21T06:20:00.000Z",
  "updated_at": "2026-09-21T06:20:00.000Z",
  "completed_at": null,
  "idempotent": false
}

同键同规范化请求重放返回 200、idempotent:true。重放返回当前对象投影，包含状态及 status_version。执行取消等写入前应重新查询当前状态与版本，不要沿用之前保存的版本。

7.2 创建账号配置需求

使用同一 POST 路径和幂等规则：

{
  "request_type": "PARTNER_ACCOUNT_REQUIREMENT",
  "category": "健身与生活方式",
  "region": "US",
  "language": "en",
  "content_format": "短视频",
  "follower_min": 10000,
  "follower_max": 100000,
  "count": 3,
  "note": "偏好近期持续发布公开内容的账号"
}

地区、语言与内容形式当前是受长度限制的文本，并非已有服务目录维护的标准枚举。成功形态同 7.1，类型和标题随需求变化。未知字段会导致 400 INVALID_CUSTOMER_REQUEST。

7.3 工单列表

GET /v1/customer/requests

返回 { "requests": [...] }，按创建时间倒序，最多最近 100 条。当前没有分页游标，也不支持客户状态或类型筛选参数。

列表每条包含以下字段：

可通过工单列表或工单详情读取最新 status_version。列表仅返回最近 100 条；更早的工单可使用保存的 request_id 查询详情。

7.4 工单详情

GET /v1/customer/requests/{request_id}

HTTP 200 响应示例：

{
  "request_id": "request_33333333333333333333333333333333",
  "request_type": "METRIC_TARGET",
  "title": "公开账号指标需求 · 1 个链接",
  "status": "RECEIVED",
  "status_version": 1,
  "created_at": "2026-09-21T06:20:00.000Z",
  "updated_at": "2026-09-21T06:20:00.000Z",
  "completed_at": null,
  "payload": {
    "links": ["https://www.instagram.com/example/"],
    "target_followers": 10000,
    "target_plays": 0,
    "target_likes": 0,
    "target_comments": 0,
    "note": "请评估公开主页的目标需求"
  }
}

详情返回当前 status_version，可用于后续取消请求。详情不提供完整报价、候选账号、交付附件或事件历史；与数据任务文件清单不是同一资源。

7.5 状态与取消

通常流程是 RECEIVED → ACCEPTED → PROCESSING → COMPLETED → DELIVERED；修订处理可能从 COMPLETED 回到 PROCESSING。客户不能自行 PATCH 状态。期限或计费展示不等于承诺退款规则，业务条件以双方确认的服务条款为准。

POST /v1/customer/requests/{request_id}/cancel

需要幂等键；提供刚读取的版本，不要硬编码为 1：

{"status_version": 1, "reason": "计划调整"}

status_version 使用正整数当前版本；reason 可省略或 null，提供文本时最长 1000 字符。成功 200：

{
  "request_id": "request_33333333333333333333333333333333",
  "status": "CANCELLED",
  "status_version": 2,
  "billing_status": "NOT_EFFECTIVE",
  "updated_at": "2026-09-21T06:25:00.000Z",
  "idempotent": false
}

• 同键同请求重放返回已保存结果及 idempotent:true；它不是实时状态查询。
• 同键不同请求：409 IDEMPOTENCY_KEY_CONFLICT。
• RECEIVED 但版本过旧：409 STATUS_VERSION_CONFLICT，重新读取列表并人工/业务重新决策。
• 已接单或处理中、处理完成：409 CANCELLATION_REQUIRES_NEGOTIATION。
• 已交付或过期：409 REQUEST_TERMINAL。
• 已取消：200，返回当前取消状态；updated_at 可能省略。
• 不存在/越权：404 CUSTOMER_REQUEST_NOT_FOUND。

当前没有客户修改需求、撤销取消、主动接单、报价确认或重新打开终态工单接口。

8. Instagram 数据任务与文件下载

8.1 创建数据任务

POST /v1/customer/jobs，需要 Idempotency-Key。用于生成批量数据结果文件，与服务工单和数据基线分别管理。

validity 用于链接有效性检查；smart 用于数据查询。include_recent_videos 只用于本接口，不能用于基线或池。

{
  "mode": "smart",
  "targets": ["https://www.instagram.com/example/"],
  "include_recent_videos": false
}

首次成功返回 201，响应节选：

{
  "job_id": "job_44444444444444444444444444444444",
  "batch_no": "EXAMPLE-20260921-001",
  "state": "QUEUED",
  "input_count": 1,
  "part_count": 1,
  "completed_items": 0,
  "total_items": 1,
  "progress_percent": 0,
  "idempotent": false
}

同键同请求重试成功返回 200、idempotent:true 及已有作业的当前投影；不同请求复用键返回 409。月度作业额度不足返回 429；额度按 UTC 自然月计算，不能把它推定为所有其他业务的额度规则。

8.2 查询状态与进度

GET /v1/customer/jobs/{job_id}，成功 200。保存创建时返回的 job_id；当前没有公开客户 API 用于列出全部作业或取消作业。

状态判断建议：QUEUED 表示排队；CLAIMED/RUNNING 可统一显示处理中；SUCCEEDED 表示数据处理成功，但还需分别检查交付状态；FAILED 表示失败，不应把指标填成零。

数据任务结束与文件可下载是不同状态。 请同时检查任务状态、所需文件的就绪状态和文件清单。result_ready_at、xlsx_ready_at、screenshots_ready_at、delivery_completed_at 可用于展示结果时间，未发生时允许 null；end_to_end_elapsed_ms 为结果耗时，不是完成期限承诺。

GET 详情不返回完整逐目标指标 JSON，批量指标请读取 Excel；不要依赖未列明的附加字段。

文件条目示例（响应中的 artifacts 数组）：

{
  "artifacts": [
    {
      "artifact_id": "artifact_example_excel",
      "artifact_type": "full_excel",
      "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "size": 18432,
      "part_index": 0,
      "download_url": "/v1/customer/jobs/job_44444444444444444444444444444444/artifacts/artifact_example_excel"
    }
  ]
}

size 是文件字节数；part_index 用于分片识别，不应当作客户提交目标的行号。artifact_type 的已知值：

• full_excel：完整 Excel。
• shard_excel：分片 Excel。
• full_screenshots：完整截图 ZIP。
• shard_screenshots：分片截图 ZIP。

完整截图包过大时可能降级，仅交付分片；不保证每个作业始终有完整 ZIP。显示可用分片和交付状态，不要无限等待一个不会生成的完整包。

8.3 下载文件、HEAD 与断点续传

GET / HEAD /v1/customer/jobs/{job_id}/artifacts/{artifact_id}。

1. 从作业响应读取相对 download_url，用业务服务地址解析。
2. 下载仍需同一客户的 Authorization: Bearer ...；当前没有公开客户签名下载链接接口。
3. 下载器仅向已确认的服务来源发送凭据，不将 API Key 拼到 URL 或转发到其他来源。
4. HEAD 可用于检查响应头，不返回文件正文。

# DOWNLOAD_PATH 使用查询作业响应中的原值；不要猜测文件标识。
curl --fail-with-body --silent --show-error \
  "$BASE_URL$DOWNLOAD_PATH" \
  -H "Authorization: Bearer $ALPHAGROW_API_KEY" \
  --output result.xlsx

断点请求使用单段 Range: bytes=1024- 或 Range: bytes=0-1023；不要发送多段范围。续传程序必须核对 206 和 Content-Range 后再拼接文件；若收到 200，不可把完整文件直接追加到旧片段后。

404 ARTIFACT_NOT_FOUND 可能表示文件未就绪、不属于当前客户或不存在。即便 artifacts 已列出条目，也可能暂时 404：先重新查询作业状态并有限重试，不据此推断其他客户的对象是否存在。文件错误不保证总有 JSON 正文。

9. Instagram 自动更新池

池是需要周期更新的目标集合，不是一次性工单。读取需要客户池查看权限；客户 API 的所有池写操作（包括 submit）需要编辑权限。

9.1 列表与详情

GET /v1/customer/pools：

成功 200，返回 {items:[...],next_cursor:...}。没有下一页时 next_cursor:null。列表条目包含 pool_id,name,timezone,interval_minutes,active,next_run_at,pool_version,created_at,updated_at，不返回目标数；启用状态使用 active:0|1，不是详情中的 status 字段。

GET /v1/customer/pools/{pool_id}：成功 200，示例：

{
  "pool": {
    "pool_id": "refreshpool_55555555555555555555555555555555",
    "name": "公开账号观察池",
    "timezone": "Asia/Shanghai",
    "interval_minutes": 1440,
    "status": "ACTIVE",
    "next_run_at": "2026-09-22T01:00:00.000Z",
    "pool_version": 1,
    "created_at": "2026-09-21T01:00:00.000Z",
    "updated_at": "2026-09-21T01:00:00.000Z"
  },
  "targets": [
    {
      "target_id": "refreshtarget_66666666666666666666666666666666",
      "ordinal": 0,
      "input_url": "https://www.instagram.com/example/",
      "kind": "PROFILE",
      "canonical_key": "example",
      "active": 1,
      "created_at": "2026-09-21T01:00:00.000Z",
      "updated_at": "2026-09-21T01:00:00.000Z"
    }
  ]
}

以实际返回的标识和版本为准，不从示例推导 ID 生成规则。kind 为 PROFILE 或 MEDIA；canonical_key 是规范化目标键，跨业务操作仍应使用各自返回的对象 ID。

9.2 创建池

POST /v1/customer/pools，需要幂等键。

{
  "name": "公开账号观察池",
  "interval_minutes": 1440,
  "targets": ["https://www.instagram.com/example/"],
  "next_run_at": "2026-09-22T01:00:00.000Z"
}

首次成功 201：

{
  "pool_id": "refreshpool_55555555555555555555555555555555",
  "name": "公开账号观察池",
  "status": "ACTIVE",
  "pool_version": 1,
  "target_count": 1,
  "next_run_at": "2026-09-22T01:00:00.000Z"
}

新池初始启用。创建前请确认目标集合和更新周期。

9.3 修改名称、间隔和启用状态

PATCH /v1/customer/pools/{pool_id}：需要幂等键和当前 pool_version，可修改名称或间隔：

{"pool_version": 1, "name": "公开账号观察池（每日）", "interval_minutes": 1440}

成功 200 返回 pool_id,name,interval_minutes,pool_version，版本递增。

PATCH /v1/customer/pools/{pool_id}/status：

{"pool_version": 2, "status": "PAUSED"}

成功 200 返回 pool_id,status,pool_version。恢复时发送 status:"ACTIVE" 和最新版本。暂停停止后续自动更新，但不表示已经开始的任务被取消。

9.4 整体替换目标

PUT /v1/customer/pools/{pool_id}/targets，需要幂等键和当前版本：

{
  "pool_version": 3,
  "targets": ["https://www.instagram.com/example/", "https://www.instagram.com/p/ABC123xyz/"]
}

这是全量替换，不是增量追加。targets:[] 清空目标。成功 200 返回 pool_id,target_count,pool_version。修改前保存并确认完整目标集合；冲突或异常后重新 GET 核对实际版本与集合，不把本地旧列表直接覆盖回去。

9.5 请求一次更新

POST /v1/customer/pools/{pool_id}/submit，需要幂等键，不要求 pool_version。请求正文使用 {}。

成功 200：

{
  "pool_id": "refreshpool_55555555555555555555555555555555",
  "submitted": true,
  "queued_at": "2026-09-21T02:00:00.000Z"
}

submitted:true 表示已受理更新请求，不表示结果已更新；本接口不返回新作业 ID 或即时数据。暂停池不会因 submit 自动恢复，需要先显式启用。后续读取当前数据并检查指标时间和新鲜度。

9.6 删除池

DELETE /v1/customer/pools/{pool_id}：

Idempotency-Key: pool-delete-example-0001
X-Pool-Version: 4

成功 204，无响应正文，不要调用 JSON 解析器。缺少版本返回 428，版本冲突返回 409。对象删除后的同请求重试可能返回 404，不能承诺每次重复 DELETE 都返回 204。删除是破坏性操作，业务界面应先确认。

10. Instagram 当前数据与每日快照

10.1 当前池数据

GET /v1/customer/pool-data/current，需要池查看及数据可见权限。仅读取已有结果，当前没有分页参数。成功 200，以下为示例响应投影：

{
  "data_access": "VISIBLE",
  "generated_at": "2026-09-21T06:00:00.000Z",
  "metrics": ["followers", "plays", "likes", "comments"],
  "items": [
    {
      "pool_id": "refreshpool_55555555555555555555555555555555",
      "pool_name": "公开账号观察池",
      "target_id": "refreshtarget_66666666666666666666666666666666",
      "input_url": "https://www.instagram.com/example/",
      "kind": "PROFILE",
      "canonical_key": "example",
      "username": "example",
      "user_id": null,
      "owner_user_id": null,
      "followers": 0,
      "plays": null,
      "likes": null,
      "comments": null,
      "metrics_at": "2026-09-21T05:30:00.000Z",
      "freshness": "FRESH"
    }
  ]
}

• generated_at 是本次响应生成时间，不是指标更新时间。
• PROFILE 的适用指标是 followers；另外三项为 null，表示不适用，不算缺失的有效指标。
• MEDIA 可包含视频三项指标及作者粉丝数；这不代表基线媒体响应也具有同样的粉丝投影。
• metrics_at 是汇总观测时间。媒体自身与作者指标都有有效时间时，采用其中较旧的时间；它不是四个独立字段的更新时间。
• 当前数据可包括暂停池已有的有效目标；暂停自动更新不会清除已有结果。
• 同一目标在多个池中可能出现多行，不能直接把行数当作独立账号数量。

freshness 的当前规则：

先判断缺失，再判断时间。0 是完整、有效的数值。接口尚未为每个 null 提供统一原因字段；客户端应结合目标类型和 freshness 显示“不适用/部分缺失/暂无数据”，不能虚构具体失败原因。

数据不可见时返回 403，结构可能是 {data_access:"HIDDEN",items:[],message:...}，不保证包含 error 字段。应隐藏数据区并提示权限不足，而不是显示“全部为零”。

10.2 最近日报与指定日期日报

• GET /v1/customer/pool-reports/latest：最近一份已经生成的日报，不保证是今天。
• GET /v1/customer/pool-reports/{YYYY-MM-DD}：指定业务日期快照。

日报是客户级、多池汇总快照，不是每个池独立的报告接口。业务时区为 Asia/Shanghai；日期传真实日历日期，例如 2026-09-20。成功 200 的主要结构如下：

{
  "report_id": "poolreport_77777777777777777777777777777777",
  "report_date": "2026-09-20",
  "timezone": "Asia/Shanghai",
  "target_count": 1,
  "generated_at": "2026-09-20T15:15:00.000Z",
  "etag": "example-report-etag",
  "metrics": ["followers", "plays", "likes", "comments"],
  "items": [
    {
      "pool_id": "refreshpool_55555555555555555555555555555555",
      "pool_name": "公开账号观察池",
      "input_url": "https://www.instagram.com/example/",
      "target_kind": "PROFILE",
      "canonical_key": "example",
      "username": "example",
      "user_id": null,
      "owner_user_id": null,
      "followers": 0,
      "plays": null,
      "likes": null,
      "comments": null,
      "metrics_at": "2026-09-20T14:00:00.000Z",
      "freshness": "FRESH"
    }
  ]
}

注意日报行使用 target_kind，当前数据行使用 kind。target_count 是快照目标行数，并非去重后的账号数。

日报使用生成时的启用池数据。同一客户、同一业务日期的快照生成后，不因后续读取而重算。最近日报不保证是当天日报，请检查 report_date；没有对应快照时返回 404 POOL_REPORT_NOT_FOUND。读取日报不会请求更新，其指标时间和新鲜度保留快照当时的值。

10.3 ETag 与历史分页

最近/指定日期日报支持 ETag 响应头。客户端保留响应头原值（包含引号等原始格式），下一次通过 If-None-Match 原样发送；匹配时返回 304，无正文。缓存策略为 private, max-age=60，不能假定所有 API 都使用 no-store。

缓存必须按客户身份、资源和权限上下文区分；退出、更换客户或授权变化后清理本地缓存，不共享客户日报缓存。

GET /v1/customer/pool-reports：

成功 200：

{
  "items": [
    {
      "report_id": "poolreport_77777777777777777777777777777777",
      "report_date": "2026-09-20",
      "target_count": 1,
      "generated_at": "2026-09-20T15:15:00.000Z",
      "etag": "example-report-etag"
    }
  ],
  "next_cursor": null
}

按报告日期倒序；next_cursor:null 表示结束。历史列表返回摘要，不返回每日报表全部行，需再读取指定日期详情。

11. TikTok / YouTube 数据接口

11.1 权限、可用性与数据保留

本章接口需已开通对应平台权限，使用与其他客户接口相同的 API Key。调用前查询平台可用操作；查询权限不等同于更新可用性。

• 独立查询不要求池权限；池、池数据和日报读取要求池查看及数据权限，池写入和手动更新还要求池编辑权限。
• 从池发起的查询及其 Excel 下载仍受池查看及数据权限约束；失去权限后可能返回404。
• 创建查询、创建池和手动更新必须带幂等键。池 PATCH 使用版本控制，不提供持久幂等重放。
• 查询、指标结果及日报默认保留上限为28天，以 expires_at 为准；再次读取不会延长保留期限。过期后不保证可读或幂等重放。池配置不随28天自动删除。
• 保存响应中的完整 ID，不自行构造。没有查询列表接口；请自行保存 query_id。
• Social 池与 Instagram 池的参数、版本字段和报告结构不同，不可混用。本章不提供池删除、改名、目标替换、列表游标或自选日期日报接口，也不沿用 Instagram 日报的 ETag / 304 约定。

11.2 查询平台可用操作

GET /v1/customer/social/capabilities，不要求幂等键或池编辑权限。成功200，数据相关响应节选：

{
  "enabled": true,
  "can_query": true,
  "platforms": ["TIKTOK", "YOUTUBE"],
  "refresh_available": {"TIKTOK": false, "YOUTUBE": false}
}

enabled、can_query 及各平台的 refresh_available 为布尔值；platforms 是平台名称数组。未开放数据功能时，enabled 和 can_query 为 false、platforms 为空数组，各平台更新标记为 false。

先检查 can_query，再查看所选平台是否在 platforms 内；需要更新时再检查 refresh_available[platform]。平台更新标记为 false 时，不提供该平台更新操作；仍可在查询已获允许时读取已有数据。标记为 true 不保证每次请求成功，提交和结果仍需按实际 HTTP 状态及逐项状态处理。未开放的业务接口可能返回 404 NOT_FOUND。

11.3 平台链接与指标结构

platform 必须精确为 YOUTUBE 或 TIKTOK，一个请求不能混平台。targets 为1–50个公开 HTTPS URL，每项最长2048字符，去除首尾空白后验证；重复输入保留原顺序和 ordinal。不接受凭据、显式端口、非法主机、短链跳转或不支持的路径。

TikTok 的 vm/vt 短链及图文链接、YouTube /c/ 旧别名和主页视频列表子路径不支持。不要假定 YouTube handle 与频道 ID 两种链接必然返回同一份已有数据。

结果中的 snapshot 结构如下：

YouTube 的 followers 表示订阅数；视频的 followers 表示作者指标。0为有效值，null为未知或不适用。主页的播放、点赞、评论通常为 not_applicable，不是主页所有视频的累计指标。fetched_at 为该指标的数据时间，各指标可不同；precision 如有值，描述数值精度（如订阅数取整）。reason 常见 CACHE_MISS、not_available、not_applicable、invalid_count，应兼容新增原因，不把未知值补零。

11.4 创建数据查询

POST /v1/customer/social/queries，要求幂等键和 JSON 正文，正文上限128000字节。

只接受这三个字段，未知字段或非布尔更新参数返回 400 INVALID_SOCIAL_QUERY。

{
  "platform": "YOUTUBE",
  "targets": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"],
  "refresh_latest": false
}

首次读取已有数据返回201，首次请求更新返回202，同键同请求重放返回200。三者均返回查询对象。请求更新不是同步返回最新读数的保证；请保存 query_id 并查询结果。

以下为未命中已有数据的响应示例，CACHED 表示已有数据查询已完成，不保证有数值：

{
  "query_id": "socialquery_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "platform": "YOUTUBE",
  "refresh_latest": false,
  "created_at": "2026-09-21T00:00:00.000Z",
  "expires_at": "2026-10-19T00:00:00.000Z",
  "state": "CACHED",
  "items": [{
    "ordinal": 0,
    "input": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "state": "CACHED",
    "reason": null,
    "snapshot": {
      "target": {"platform":"YOUTUBE","kind":"MEDIA","external_id":"dQw4w9WgXcQ","canonical_url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"},
      "owner": null,
      "metrics": {
        "followers":{"value":null,"fetched_at":null,"reason":"CACHE_MISS"},
        "plays":{"value":null,"fetched_at":null,"reason":"CACHE_MISS"},
        "likes":{"value":null,"fetched_at":null,"reason":"CACHE_MISS"},
        "comments":{"value":null,"fetched_at":null,"reason":"CACHE_MISS"}
      }
    }
  }]
}

11.5 查询状态与导出

GET /v1/customer/social/queries/{query_id}：无需正文或额外参数，200返回11.4的查询结构。

CACHED为已有数据查询完成；QUEUED为等待处理；RUNNING/WAITING为处理中；SUCCEEDED、PARTIAL_SUCCEEDED、FAILED分别为成功、部分成功和失败。items[].reason 解释条目状态，可为 null；每个指标也有自己的 reason，部分指标缺失不一定导致整项 FAILED。

使用原 query_id 退避轮询，达到总状态 CACHED、SUCCEEDED、PARTIAL_SUCCEEDED 或 FAILED 后停止。不存在、过期或不可访问的查询返回 404 QUERY_NOT_FOUND。每客户最多允许200个未完成更新目标，超出返回429；同请求重复项也可能计入限制。

GET /v1/customer/social/queries/{query_id}/export.xlsx：200返回 XLSX 二进制，Content-Type 为 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet，附件名 alphagrow-data.xlsx，Cache-Control: private, no-store。下载仍要求 API Key，且遵守查询权限和保留期限。

导出使用当前查询结果，允许在未完成时下载；建议等终态后下载，并核对逐项状态。0保持数字，未知值留空并附原因；公式样式输入作为文本。不存在、过期或不可访问时返回404。此下载接口不提供 HEAD 或 Range 契约，不套用第8章续传方式。

11.6 创建与列出自动更新池

GET /v1/customer/social/pools：200返回 {items:[...]}，按创建时间倒序，最多100个，无游标。条目字段为 pool_id,platform,name,automatic,interval_seconds,next_run_at,latest_query_id,version,created_at,updated_at，不含 targets。列表 automatic 为整数0/1，详情则为布尔值；尚无查询时 latest_query_id:null。

POST /v1/customer/social/pools：要求池编辑权限和幂等键，只接受以下字段：

{
  "platform": "TIKTOK",
  "name": "示例公开视频池",
  "targets": ["https://www.tiktok.com/@example"],
  "automatic": false,
  "interval_seconds": 86400
}

首次201返回 {pool_id,version:1}；相同幂等重放200返回原 pool_id 及当前 version。每客户最多100个 social 池，超限429；automatic:true 需要平台更新可用，否则503。创建成功不表示指标已经更新。

11.7 池详情与自动更新设置

GET /v1/customer/social/pools/{pool_id}：成功200：

{
  "pool_id": "socialpool_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "platform": "TIKTOK",
  "name": "示例公开视频池",
  "targets": ["https://www.tiktok.com/@example"],
  "automatic": false,
  "interval_seconds": 86400,
  "version": 1,
  "latest_query_id": null
}

详情不返回列表中的 next_run_at、created_at、updated_at。不存在或不可访问返回 404 POOL_NOT_FOUND。

PATCH /v1/customer/social/pools/{pool_id}：要求池编辑权限，正文仅允许且必须提供整数 version 和布尔值 automatic：

{"version":1,"automatic":true}

200返回 {pool_id,version:2}，旧版本返回 409 VERSION_CONFLICT。本操作没有持久幂等键语义；请求结果不确定时先 GET 读取，不用旧版本循环重试。启用时更新不可用返回503。只能切换自动更新，不能修改名称、周期或目标。关闭自动更新不影响另外获授权的独立查询或手动更新。

11.8 池当前数据与手动更新

GET /v1/customer/social/pools/{pool_id}/data：200返回 {pool_id,items:[{snapshot:SocialSnapshot},...]}，snapshot结构见11.3，顺序对应池 targets，含未命中的结果。不含 query_id 或逐项任务状态，读取本身不请求更新。

POST /v1/customer/social/pools/{pool_id}/refresh：要求池编辑权限和幂等键，正文必须为 {}，不接受目标或其他选项。使用池中目标请求更新，返回查询对象（同11.4），并更新池的 latest_query_id。首次202、幂等重放200；automatic=false 时也可手动更新，更新不可用返回503。

重放不会创建新一轮更新。需要新一轮时使用新键；不要复用独立查询的操作键，改变操作来源可能返回409。

11.9 日报列表、最新日报与详情

GET /v1/customer/social/reports：200返回 {items:[{report_id,pool_id,report_date,generated_at},...]}，只含未过期日报，按 report_date 倒序、pool_id 排序，最多100个；无游标或 pool_id 筛选参数。

GET /v1/customer/social/reports/latest：200返回当前客户所有 social 池中最新一份未过期日报，按 report_date、generated_at 倒序选择；不是每池一份，也不保证为当天日报。

GET /v1/customer/social/reports/{report_id}：200返回指定日报。两种详情均包含 report_id,pool_id,report_date,generated_at，以及 query_id,platform,refresh_latest,created_at,expires_at,state,items 查询快照字段（同11.4）；无可读日报返回 404 REPORT_NOT_FOUND。

日报记录已完成更新的结果，也可包含失败或部分成功。report_date 为查询 created_at 对应的 Asia/Shanghai 日期，不是下载日期。同池同日的日报可能由较新查询更新，不应视为不可变归档。generated_at 不是指标 fetched_at，保留期限继承查询，不因再次生成延长。尚无已完成更新或日报尚未就绪时可能无日报；暂停池仍可能有可读历史日报。GET 不创建日报。

11.10 错误与处理

错误核心结构为 {"error":"CODE"}；部分响应还包含追踪用 request_id，不保证始终存在。

已接受的查询也可能返回 FAILED 及逐项 reason。创建成功不等于更新成功，不自动反复 POST。共享鉴权和限流错误见第13章。

12. 幂等、版本、限流与重试

12.1 幂等键适用范围

Idempotency-Key: request-create-example-0001

需要幂等键的接口使用 8–128 字符，允许英文字母、数字、.、_、:、-，即 ^[A-Za-z0-9._:-]{8,128}$。建议为每次业务操作生成唯一键，并持久保存“操作类型、目标、原始请求体、幂等键、响应标识”。

幂等键应包含操作前缀或使用全局唯一值，不在不同对象/接口间重复使用同一个固定键。各业务类别在客户范围内共享各自的幂等记录空间；同一客户换 API Key 不意味着重新获得独立空间。

Instagram 池操作特别注意： 重试时保持 JSON 字段顺序不变，字段顺序变化也可能造成幂等冲突。部分失败请求可能已经占用键；修正参数后使用新键，不承诺“所有 400 都可用原键改正文重试”。遇到 IDEMPOTENCY_REQUEST_IN_PROGRESS 不要立即更换键重复创建，应先退避并核实状态。

本文不承诺幂等记录的统一保留时长；不可把幂等机制当永久业务主键或跨接口事务。

12.2 乐观版本控制

• Instagram 池修改使用请求体 pool_version；删除使用请求头 X-Pool-Version。Social 池修改使用 version，冲突代码为 VERSION_CONFLICT。
• 工单取消使用 status_version。请从工单详情或列表重新读取当前版本；不要长期复用创建时的版本。
• 缺少池版本为 428 POOL_VERSION_REQUIRED；池版本过旧为 409 POOL_VERSION_CONFLICT。
• 工单版本冲突为 409 STATUS_VERSION_CONFLICT。

发生冲突：重新读取 → 比较他人的修改 → 决定是否继续 → 使用最新版本和新的业务操作幂等键。不要自动把旧请求中的版本数字加一后盲目重发。

12.3 限流与额度

分钟请求限额按客户计算，同客户多个 API Key 共用，不是每个 Key 各有一份额度。触发限流时通常返回 429 RATE_LIMIT_EXCEEDED，并通过 Retry-After 指示等待秒数。

创建作业另受月度作业数限制，超额返回 429 MONTHLY_JOB_LIMIT_EXCEEDED，等待时间按下一个 UTC 月度窗口计算。实际额度由客户配置决定；本文不预设每分钟数量、套餐价格或购买额度方式。

12.4 推荐客户端重试策略

以下是集成建议，不是服务端 SLA：

1. GET/HEAD 的网络错误或暂时性 5xx：采用带随机抖动的指数退避，例如 2、4、8、16、30 秒，设置总超时和最大次数。
2. 429 优先遵循 Retry-After，不要通过增加 API Key 或并发绕过客户额度。
3. 有幂等保护的写请求遇到网络超时：使用原键、原正文、原版本重试，先找回结果；确认需要变更业务内容后才生成新操作。
4. 无幂等保护的基线 POST：不要在网关层无限自动重试；若未收到 ID，先核实业务记录，再决定是否重新创建。
5. 400/401/403/428 不做无差别自动重试；修正参数、认证或权限。409 按具体冲突处理。
6. 作业与基线刷新分别按其状态轮询，并逐渐拉长间隔。作业达到 SUCCEEDED 或进度 100% 不代表文件交付完成；仍需对所需 Excel/截图交付进行有限轮询，直至相应交付就绪、明确失败或降级得到处理，或达到客户端超时。下载临时404应结合交付状态有限重试。
7. 204、304、HEAD 和部分文件错误无 JSON 正文，先看 HTTP 状态与 Content-Type，再解析正文。

13. 错误处理

不同接口当前未完全统一错误封装。常见示例：

{"error": "INVALID_IDEMPOTENCY_KEY"}

响应还可能包含 message、details 或用于错误追踪的 request_id，但不能假定它们始终存在。工单成功响应中的 request_id 是业务工单 ID，不等于错误追踪 ID。

错误处理以 HTTP 状态 + 可用业务代码为主，不依赖中文/英文 message 的完整文本匹配。未知代码保留通用错误提示及脱敏诊断记录；不要把原始服务端响应或技术堆栈直接展示给客户最终用户。

TikTok / YouTube 专用错误见11.10。排查问题时提供方法、路径、时间、HTTP 状态、错误代码及可用追踪 ID，不提供 API Key 或其他凭据。