socialcrawl

SocialCrawl API

一个 API 密钥，一个响应封装，适用于社交、电商和研究数据。列表格式为 { items, next_cursor?, total? }；添加 ?format=raw 可跳过转换流程。以下文件均位于 references/ 中；只打开任务需要的文件。

API 密钥

仅在需要进行实时 API 调用时解析 API 密钥。有关文档、功能、定价和代码生成的问题无需密钥。

按以下顺序检查这些来源，不要显示其内容：

1. 环境变量： 当 SOCIALCRAWL_API_KEY 以 sc_ 开头且不是示例占位符时使用它。
2. 配置文件： 如果环境变量不存在，将 ~/.config/socialcrawl/api_key 加载到当前进程的 SOCIALCRAWL_API_KEY 中。在 POSIX shell 中，使用 SOCIALCRAWL_API_KEY="$(<"$HOME/.config/socialcrawl/api_key")"; export SOCIALCRAWL_API_KEY。在 PowerShell 中，使用 $env:SOCIALCRAWL_API_KEY = (Get-Content -LiteralPath "$HOME/.config/socialcrawl/api_key" -Raw).Trim()。
3. 缺少密钥： 告知用户在 https://socialcrawl.dev/dashboard 创建或轮换密钥，并将其配置为 SOCIALCRAWL_API_KEY 或存入 ~/.config/socialcrawl/api_key。不要让他们在聊天中粘贴密钥。在他们确认已配置之前，停止实时调用。

绝不要打印、粘贴、记录或返回密钥。绝不要在生成的代码、命令、URL、错误消息或保存的对话记录中写入明文密钥。在示例中，将 $SOCIALCRAWL_API_KEY（POSIX）或 $env:SOCIALCRAWL_API_KEY（PowerShell）保留为变量引用。如果密钥出现在聊天或输出中，建议用户在控制面板中撤销该密钥并创建替代密钥。

首次实时调用

在会话中首次进行实时调用前：

1. 按上述步骤解析 API 密钥。如果密钥缺失或为占位符，停止调用。
2. 使用免费的余额端点（0 个额度）验证密钥：

   curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" "https://www.socialcrawl.dev/v1/credits/balance"
   

3. 如果成功，显示余额并继续处理用户的请求。
4. 如果失败，报告错误，但不要包含请求标头或密钥，然后按照 references/errors.md 操作。

新鲜度检查（每个会话执行一次）

此文件是注册表的快照，其指纹为：

registry_fingerprint: 61a90b6d5dadcc038c3e4d4165f85f74177c77c5c5dfc9c2b7712c2f5d4ddaa4
generated_at: 2026-10-07

除了余额检查外，再进行一次免费调用：

curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" "https://www.socialcrawl.dev/v1/utility/endpoints?fingerprint=1" | head -c 400

• data.fingerprint 等于上方的 registry_fingerprint - 使用随附文件并继续。
• 两者不同 - 此副本与实时 API 不同步（技能或服务端可能较新）：价格、参数或端点已更改。以实时注册表为准，并通过 /v1/utility/*（全部免费）查询文件中无法解答的内容。只需简短告知用户一次：“此 SocialCrawl 技能与实时 API 不匹配；运行 npx skills update socialcrawl --yes 进行更新。”然后回答用户的实际问题。不要重复提醒，也不要征求许可。
• 没有 data.fingerprint（返回 404，或较旧的服务端返回普通列表）- 改用数量进行比较：将 /v1/utility/endpoints 中的 data.stats.platforms 和 data.stats.endpoints 与 references/index.md 顶部的总数进行比较。实时数量更高表示落后，按上述方式处理。
• 调用失败（尚无密钥、离线或非 200）- 静默跳过。此检查绝不能阻碍请求。

工作流

1. 先查找调用（免费，不消耗额度，也不会执行任何操作）。 GET /v1/utility/find?task=<the job in plain words> 会按任务为端点排序，每个端点都包含 method、path、params_filled（从你的描述中提取）、missing 和 estimated_credits。当 uncertain 为 false 时，直接调用 results[0]：其 method、path 和 params 就是可直接使用的调用（补上任何 missing 参数，然后应用 Cost 规则）。当 uncertain 为 true 时，展示各个选项。对于需要多次调用的任务（例如先查个人资料，再查帖子，然后查评论；或监控品牌），GET /v1/utility/plan?query=<the job> 会按顺序返回各次调用及其参数、价格和步骤间的依赖关系。写入或计费请求不会返回结果。
2. 离线时、find 或 plan 返回 404 时（服务器版本较旧：回退到现有流程），或 uncertain 为 true 时，改用随附文件。 使用下方的常见任务进行路由，或在 references/index.md 中 grep：查看其中的“任务到方案”表，然后查看每个端点对应的一行（grep -i transcript references/index.md）。对于某个方案，只读取它所在的章节：grep -n '^## ' references/recipes.md 会给出行号；不要打开整个文件。对于某个端点，先读取平台文件的目录（从顶部到第一个 ## ），然后只读取它所在的章节：grep -nE '^## (GET|POST|PUT|PATCH|DELETE) /v1/<platform>/<resource> - ' references/<platform>.md，并从该行读到下一个 ## 。该章节包含准确的费用、缓存 TTL、分页方式、所有参数、响应字段，以及计费前会检查的约束。
3. 估算。 构建准确的请求并应用下方的费用门槛（小型固定费用调用只需一行；任何计量计费或大型请求都要按照 references/cost-gate.md 完成完整的预检）。标题中的数字可能是每行或每页的单位费用，不一定是请求总费用。
4. 调用。 解析密钥，然后严格按照章节中的说明运行请求，保留其 HTTP 方法和请求体结构。如果用户已明确要求运行此确切的付费请求，只需披露费用即可，但 Ask 级别除外：始终要征求同意（参见 Cost 规则中的门槛）；其他情况下，只有在付费调用或用户未授权的更大范围操作之前才需征求同意。
5. 报告。 返回数据，然后提供 credits_used 和 credits_remaining。对于异步任务，需报告提交时的额度冻结，以及完成后的最终扣费。

常见任务

针对 Agent 最常遇到的需求，以下是注册表配方生成的首次调用（{x} 由你填写）。find 会使用你填写的值返回相同答案。

任务	首次调用	然后
将帖子的评论导出为 CSV	GET /v1/tiktok/post/comments?url={url}&sort=recent&scan_pages=3	将 paginate.py 的输出传递给 to_csv.py --archetype Comment；任何平台的 <platform>/post/comments；配方
按细分领域、粉丝数或国家查找创作者	GET /v1/search/creators?query={niche}&sources=tiktok,instagram&min_followers={min_followers}	search/creators 不支持按国家筛选；配方；单个国家：配方；小预算下查找单个国家的创作者：配方
汇总某产品在各零售商处的评价	GET /v1/prism/product-reviews?query={product}	涵盖 Amazon、Google Shopping 和 Trustpilot 的评价；Walmart、Target、Home Depot：<retailer>/reviews；配方
股价和新闻	GET /v1/finance/ticker-search?keyword={company}	然后调用 finance/quote（quote.price.current）和 finance/news；配方
YouTube 字幕稿	GET /v1/youtube/video/transcript?url={url}	配方
有新帖子或内容变更时发出提醒	POST /v1/monitors（请求体 recipe: instagram/profile/posts）	仅当 GET /v1/utility/estimate?id=monitors 返回 200 时，先发送 ?dry_run=1，在不创建监控的情况下进行验证并估价；否则说明请求内容，且在用户同意前不要创建任何内容；单个页面：web/monitors；配方
获取一组帖子 URL 的统计数据	POST /v1/prism/post-stats（JSON 请求体 urls）	URL 文件：batch.py --urls；配方
韩国 / Naver 搜索	GET /v1/naver/brief?query={keyword}&corpora=news,blog,cafearticle	单个语料：naver/blog/search、naver/news/search；配方
查询个人资料	GET /v1/tiktok/profile?handle={handle}	任何 <platform>/profile；多个用户名：prism/profiles；配方
抓取网页	GET /v1/web/scrape?url={url}	获取结构化字段：web/extract；抓取整个网站：web/crawl
搜索网络上的品牌提及	GET /v1/prism/brand-mentions?keyword={brand}&date_from={start_date}&include=digest	配方
在多个平台搜索同一主题	GET /v1/search/multi?query={topic}&platforms=tiktok,instagram,youtube&relevance=filter	配方

辅助工具

scripts/ 中包含打包的脚本（Python 3）。这些脚本从 SOCIALCRAWL_API_KEY 或 ~/.config/socialcrawl/api_key 读取密钥，且绝不会打印密钥；运行每个脚本的 --help 可查看其他说明。

python3 scripts/sc.py tiktok/profile handle=nike          # one call; JSON to stdout, credits_used to stderr
python3 scripts/paginate.py tiktok/post/comments --items 500 --max-credits 20 url=<post_url> > rows.jsonl   # page to N rows within a budget
python3 scripts/to_csv.py --archetype Comment --in rows.jsonl --out comments.csv   # rows to CSV with stable columns
python3 scripts/batch.py --urls links.txt > stats.jsonl   # stats for a file of post URLs (prism/post-stats, or one prism/jobs job past 500)
python3 scripts/estimate.py tiktok/post/comments --items 500 --offline url=<post_url>   # quote offline from assets/endpoints.json

**代码请求：**阅读相关章节并进行成本评估，编写一段从环境变量读取 SOCIALCRAWL_API_KEY 的代码片段，并添加注释说明计费单位，然后直接提供代码，不要运行。

**功能与定价问题：**根据索引和 references/pricing.md 回答（成本、套餐、额度包、退款、免费端点列表）。认证、信封、分页、标签、缓存、幂等性：请参阅 references/api-overview.md。免费的 /v1/utility/* 调用通过实时注册表查询：endpoints（使用 ?platform=、?search= 筛选）、endpoint?id=tiktok/profile（单个端点及实测字段填充率）、plan?query=、quickstart。

**平台不明确：**如果用户只说“获取 @nike 的个人资料”而未指定平台，请询问具体是哪个平台。

查阅位置

需求	打开
任意单个平台（社交、商业、评论与地点、应用商店、搜索/新闻/金融、研究与开发、个人简介链接）	index.md 列出所有平台文件及其端点数量；打开 references/<platform>.md
一次调用覆盖多个平台：Prism 组合接口、search/multi、search/everywhere	prism.md、search.md
通过 Webhook 交付的定时重复运行	monitors.md
“我的账号列表中，哪些账号发布了关于 X 的内容？”（Cohorts，而非监听）	cohorts.md
单次请求或完整分页遍历的成本	cost-gate.md、pricing.md
调用失败	errors.md

切勿仅凭此表回答“不支持”。 此表可能不如本文件更新，缺少某行往往意味着副本已过时，而非确实不支持。在告知用户某个平台、端点或功能不存在之前，请检查实时注册表——此操作免费：

curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  "https://www.socialcrawl.dev/v1/utility/endpoints?search=douyin"

每行都包含 path、method、credits_label、required_params、one_of、optional_params、paginated 和 cache_ttl_seconds：这些信息足以在不查阅本文件的情况下发起调用。只有当搜索结果返回 total: 0 时，才能说该功能不受支持。

**跨零售商比较商品：**Amazon、Walmart、Target、eBay 和 Home Depot 使用相同的规范化 Product / Review / Seller 架构，因此各行数据可以对齐。先分别使用各零售商自己的搜索功能解析商品 ID（ASIN、商品 ID、TCIN 等），然后分别获取商品详情和评论。/v1/prism/product-reviews 是一个组合接口，仅涵盖 Amazon、Google Shopping 和 Trustpilot 的评论；对于 Walmart、Target 或 Home Depot，请调用 <retailer>/reviews。

同时查询多个平台：/v1/search/multi 会在多个平台各自的搜索中运行同一查询（按各平台的页面价格计费，且仅对返回结果的平台收费）；/v1/search/everywhere（20 个额度）会为最多 17 个来源制定计划、排序并聚类；多个个人资料或帖子 URL 请使用 POST /v1/prism/profiles / POST /v1/prism/post-stats，或后台任务 POST /v1/prism/jobs。

发起调用

基础 URL 为 https://www.socialcrawl.dev。大多数端点使用带查询参数的 GET 请求（对值进行 URL 编码）：

curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  "https://www.socialcrawl.dev/v1/{platform}/{resource}?{param}={value}"

切勿假定请求方法。 每个端点章节都以其实际请求方法为标题，并提供可运行的 curl 命令。批量读取、Prism 任务、Web 任务、监控和群组使用 POST、PATCH、PUT 或 DELETE，并设置 content-type: application/json（web/parse 使用 multipart）；端点列表，以及流式调用（Accept: text/event-stream）和需要使用先前调用返回的 ID 的两步端点，见 api-overview.md。速率限制：每个密钥每分钟 600 次请求，最多 50 个并发请求；超出时均会返回 429 和 Retry-After，且永不收费。某些端点需要轮询任务，耗时 10-45 秒：请使用 60 秒超时。

读取响应

详情见 api-overview.md。首次调用前请牢记以下五条规则：

• 字段位置。 pagination（next_cursor、has_more、page_size）和可选的 meta.hint 位于响应封装的根级。dropped、_warnings 以及每页的所有报告（labels、relevance、label_share、hydration、walk 等）均位于 data 内。请读取 data._warnings：被忽略的参数（count was ignored; use limit (page size)）或解析到其他账号的用户名（resolved_to_different_handle）会在这里报告，而不是作为错误返回。
• 分页。 将 pagination.next_cursor 作为 cursor 传回，并在 has_more: false 时停止，而不是根据页面条数较少或 total 停止。匹配结果为零的列表会以 200 返回 items: []，费用为 0 个额度。
• 默认判定免费。 评论、帖子、评价和关键词搜索结果行都包含标签（computed.labels），搜索结果行还包含相关性分数（computed.relevance），且不额外收费；judgments=off 会移除这些信息。选择启用的预设项（label=spam|toxic|low_quality|quality|injection|mention、relevant_to=）会按每新增判定 25 行收取 1 个额度。使用查询词进行 relevance=filter 筛选是免费的。
• 费用控制。 创作者帖子列表支持 stop_at_id / since，使轮询只为新页面付费（pagination.stopped_at 会说明停止原因）。关键词搜索支持 min_views、max_age_days、country / exclude_country、sort_rows=views、seen=<id>（重复项会退款）和 max_pages（1-5，每页均收费）。
• meta.hint 会指出另一个能以更少步骤完成任务的调用。如果该调用费用更高，提示消息会说明价格；仅在用户授权范围内遵循提示。

include= 水合会将结果行与同级端点合并，并在页面费用之外按行收费，因此引用水合调用的费用时，切勿只报普通标题所示的费用；上限见 cost-gate.md，相关注意事项见 api-overview.md。

费用规则

缓存命中、幂等重放、所有 /v1/utility/* 端点以及 /v1/credits/balance 均消耗 0 积分。失败的调用会退款；因参数错误、页码超出末页或触发速率限制而被拒绝的请求不会扣除积分。计费端点会预先冻结一个上限，并按实际完成的工作量退款，因此响应中的 credits_used 就是实际费用。请针对确切请求报价总费用，而不是端点的基础费用或单位费用。根据调用规模设置门槛：

调用	门槛
固定价格 ≤ 5 积分，且用户已提出请求	一行报价：≈ N credits
按量计费、多页、批量、监控/群组，或 > 25 积分	使用 estimate.py / utility/estimate 完整预检
预先冻结的上限（最坏情况）> 500 积分或超出预算（用户说明的预算）	调用前先询问

对于介于两者之间的情况，或不确定价格或参数时：先使用免费的 GET /v1/utility/estimate?id=<platform/resource>&<params> 报价。除 404 以外的任何响应都表示服务端版本较新（5xx 或网络故障不算响应：请重试估算）；使用其报价，之后在任何端点上使用 dry_run=1 均免费（只验证，不获取数据）。404 或 ENDPOINT_NOT_FOUND 表示服务端版本较旧：不要发送 dry_run=1（此时会按普通调用计费，除非端点文档明确标注该干运行免收费）；请使用 scripts/estimate.py（离线，读取 assets/endpoints.json）或该部分的 Pricing 行报价。无论何种情况，之后都要报告 credits_used。

如果任务需要获取完整列表，必须在请求第一页之前估算遍历全部页面的费用。 翻页直至完成的费用会按页数累加，而标题只显示一页。instagram/followers 和 instagram/following 的 coverage=full 是极端情况：每页 10 积分、每页约 50 个账号，因此包含 2,600 个账号的列表大约需要 520 积分。请报出总费用并在开始前征得同意（多页遍历）。

错误：重试前，先根据 references/errors.md 对错误进行分类。积分与余额：GET /v1/credits/balance（0 积分）；账本为 GET /v1/credits/transactions?limit=50（0 积分）。