跳转到主要内容
POST
达人研究
各 action 返回归一的 output,缺失值为 null。Provider 原始输出保留在 Run 上,可通过 Get Run 读取。search 和 content 返回达人 items[] 与分页信息;content 仅在当前页归并作者,并保留 matching_posts[] 作为证据。profile 返回请求平台账号、关联 profiles[] 和 contacts[]。contact 返回 contacts[]。shop 返回账号、Kalodata 标识、市场、币种、时间范围、独立销售指标及联系方式。保留联系方式的 usage 和 verified;未知值不表示商务或已验证。Provider 互动率与 Kalodata 估算保留原有含义。 分别检查业务 result_status 和 Run status。no_result 保留 action 的空结构。charge_usd 合计所列 runs 的费用,结算前为 null。通过需要认证的 result_url 读取待完成结果;不创建新 Run,也不恢复兜底。

请求头

idempotency-key
string
必填

每次独立查询都生成新的唯一值(建议使用随机 UUID),即使参数相同且发生在同一天。仅在恢复同一次预期执行时沿用原键与参数,取回原 Run,不再次扣费。同键更改执行参数返回 409;更换 task_id 或 metadata 不会创建新 Run。旧的不透明键仍可用于恢复。

Minimum string length: 1

请求体

application/json

search:按 query 搜 TikTok/Threads 账号。content:搜 Instagram/YouTube 内容,按作者在当前页归并。profile:按 handle 补全 influencersclub 档案。contact:按 handle 查询联系方式。shop:用 Kalodata creator_id、region、language、currency、date_range 查 TikTok Shop 详情。不支持的筛选在创建 Run 前拒绝。粉丝数与推广预算在发现候选后筛选,不是搜索条件。

action
enum<string>
必填
可用选项:
search,
content,
profile,
contact,
shop
platform
enum<string>
必填
可用选项:
tiktok,
threads,
instagram,
youtube,
x,
twitch,
onlyfans
provider
enum<string> | null

默认为 auto,按 Glasser 偏好顺序选择第一家符合条件的数据提供商。指定的数据提供商必须支持请求且获得当前 API Key 的允许,不会切换到其他家。可用值见下方。

可用选项:
auto,
scrapecreators,
tikhub,
influencersclub,
kalodata,
apify
query
string | null
Required string length: 1 - 500
handle
string | null
Required string length: 1 - 2048
cursor
string | null
Required string length: 1 - 4096
require_email
boolean | null

仅 profile/contact 经 influencersclub 支持:true 对应 email_required=must_have,false 对应 preferred。其他 Provider 拒绝此筛选。

creator_id
string | null

仅 shop:Kalodata creator_id。不要假设其他平台的用户 ID 可直接替用。

Required string length: 1 - 100
region
string | null
Minimum string length: 1
language
string | null
Minimum string length: 1
currency
string | null
Minimum string length: 1
date_range
string | null
Minimum string length: 1
category_ids
integer[] | null
shop_id
string | null
Minimum string length: 1
need_extra
boolean | null
task_id
string | null

将相关 Run,包括自动切换产生的 Run,归入同一个 Task。复用稳定字符串,并通过 Task 筛选 Run 列表。

metadata

可选追踪字段,随 Run 返回,也可用于筛选。不会发送给数据提供商,也不影响路由、价格或幂等。

  • 最多 20 个键:小写字母、数字和下划线,以字母开头,最长 40 个字符。
  • 值:长度为 1–500 的字符串。
  • user_id:终端用户的不透明 ID,不得使用邮箱或姓名。

无效条目整体丢弃,不截断。请求继续执行,Run 返回实际保存的字段。

响应

成功

id
string
必填
run_url
string
必填

在控制台打开 Run,需要工作空间成员权限。

provider
string
必填
Pattern: ^[a-z0-9][a-z0-9-]*$
endpoint
string
必填
Pattern: ^\/.+$
endpoint_version
integer
必填
status
enum<string>
必填

QUEUED 或 RUNNING 表示仍在执行。COMPLETED 表示已有数据提供商响应,包括非 2xx 响应。FAILED 请读取 failure。STOPPED 表示分派前停止。charge_usd 与状态分别检查。

可用选项:
QUEUED,
RUNNING,
COMPLETED,
FAILED,
STOPPED
failure
object | null
必填

Run 失败原因,仅在 status 为 FAILED 时非 null。

input
object
必填
output
object
必填
provider_response
object | null
必填

仅在 status 为 COMPLETED 时非 null。

  • 2xx 响应:output 为任意结构的数据提供商原生 JSON;正文为空时为 null。
  • 非 2xx 响应:error 包含数据提供商错误正文,output 为 null。

两种正文均会移除敏感字段。

charge_usd
string | null
必填

所列 Run 的历史费用总和,包括重放或读取的 Run。所有 Run 结算前为 null。这不是当前请求的新增支出;request_charge 单独报告新增费用。失败也可能收费。

Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
charge_basis
object | null
必填

单个 Run 的计费依据;多个 Run 汇总时为 null。各项费用请查看 runs[].charge_basis。

stoppable
boolean
必填

当前是否可接受停止请求。不保证能在分派前停止 Run。

stop_requested_at
string<date-time> | null
必填

请求停止的时间。如果已开始分派,Run 仍可能继续。

created_at
string<date-time>
必填

ISO 8601 UTC 时间戳。

started_at
string<date-time> | null
必填

ISO 8601 UTC 时间戳。

completed_at
string<date-time> | null
必填

ISO 8601 UTC 时间戳。

task_id
string | null
必填
metadata
object
必填

已保存的追踪字段,可用于筛选 Run,不发送给数据提供商,不影响路由、价格或幂等。

  • 最多 20 个键:小写字母、数字和下划线,以字母开头,最长 40 个字符。
  • 值:长度为 1–500 的字符串。
  • user_id:终端用户的不透明 ID,不得使用邮箱或姓名。
action
enum<string>
必填
可用选项:
search,
content,
profile,
contact,
shop
result_status
enum<string>
必填
可用选项:
success,
no_result,
error,
pending
error
object | null
必填
runs
object[]
必填
result_url
string
必填

通过认证读取规范化结果和总费用的只读 URL 路径,配合 API 服务地址使用。不创建 Run,也不恢复切换。GET /v1/runs/:id 仍返回原生单个 Run。

response_file
object

以 JSON 文件完整交付较大的 Provider 正文。Glasser 对接收的正文和序列化文件应用 32 MiB 的运行时资源保护。body_field 指明被替代的字段;output 为 null,或省略 provider_response.error。下载链接最多一小时后过期。在文件的 7 天可用期内,通过已认证的 Get Run 刷新链接。读取和下载不会再次执行 Run 或重复收费。state 为 link_pending 时,读取同一 Run 即可准备链接,不会再次执行或重复收费。链接授予临时读取权限,请仅与预期接收者分享。

review_invitation
object

每个 Run 至多出现一次,只在部分已完成 Run 的首次交付中出现。用完本次结果后,按 instruction 提交评价,然后继续任务。可选;不影响 Run 及其费用。

request_charge
object

当前请求的受理与费用证据。在同一件用户工作中保存 created_run_ids,每个已结算 Run 只计一次费用。更换 task_id 不会把幂等重放变成新 Run。读取结果的费用为零,受理列表为空。