Back to Details

socialcrawl

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SocialCrawl API

SocialCrawl API

Unified social media data API. One API key, one response format, 21 platforms, 105 endpoints.
统一的社交媒体数据API。一个API Key，统一响应格式，覆盖21个平台，105个端点。

API Key

API Key

Resolve the API key before making any call, checking these sources in order:
  1. Env var: 
    echo "$SOCIALCRAWL_API_KEY"
    — if set and starts with 
    sc_
    (and is not a placeholder like 
    sc_your_api_key_here
    ), use it.
  2. Config file: 
    cat ~/.config/socialcrawl/api_key 2>/dev/null
    — if the file exists and contains a key starting with 
    sc_
    , use it.
  3. Ask the user: If neither source has a valid key:
    • Tell the user: "I need your SocialCrawl API key to continue. You can find it at https://socialcrawl.dev/dashboard — every account starts with 100 free credits."
    • Ask them to paste their key.
    • After receiving the key, auto-save it so they never need to paste it again:
      bash
      mkdir -p ~/.config/socialcrawl && echo "sc_xxxxx" > ~/.config/socialcrawl/api_key
    • Tell the user: "I've saved your key to 
      ~/.config/socialcrawl/api_key
      so it will be available in future sessions."
For all subsequent API calls in the session, use the resolved key directly in the curl command (do not rely on the env var being set).
发起任何调用前先解析API密钥，按以下顺序优先获取：
  1. 环境变量：
    echo "$SOCIALCRAWL_API_KEY"
    — 如果已设置且以
    sc_
    开头（且不是
    sc_your_api_key_here
    这类占位符），则使用该值。
  2. 配置文件：
    cat ~/.config/socialcrawl/api_key 2>/dev/null
    — 如果文件存在且包含以
    sc_
    开头的密钥，则使用该值。
  3. 询问用户：如果以上来源都没有有效密钥：
    • 告知用户：「我需要你的SocialCrawl API密钥才能继续操作。你可以在 https://socialcrawl.dev/dashboard 找到密钥，所有账户注册即赠100个免费信用点。」
    • 请用户粘贴他们的密钥。
    • 收到密钥后，自动保存以便用户后续无需重复粘贴：
      bash
      mkdir -p ~/.config/socialcrawl && echo "sc_xxxxx" > ~/.config/socialcrawl/api_key
    • 告知用户：「我已将你的密钥保存到 
      ~/.config/socialcrawl/api_key
      ，后续会话可直接使用。」
会话中所有后续API调用，直接在curl命令中使用解析到的密钥（不要依赖环境变量的设置）。

First Use

首次使用

On the first interaction with this skill in a session:
  1. Briefly introduce: "SocialCrawl provides a single API for 21 social media platforms (105 endpoints). Let me verify your API key."
  2. Resolve the API key using the steps above. If the key is missing or a placeholder, stop here and ask for it before proceeding.
  3. Tell the user you'll make a test call that costs 1 credit, then run:
    bash
    curl -s -H "x-api-key: KEY" "https://www.socialcrawl.dev/v1/tiktok/profile?handle=tiktok"
    (Replace 
    KEY
    with the resolved key value.)
  4. If successful, confirm the key works and show credits_remaining. Then respond to whatever the user actually asked.
  5. If it fails, report the error and help troubleshoot (see Error Handling below).
会话中首次触发该技能的交互时：
  1. 简要介绍：「SocialCrawl为21个社交媒体平台提供统一API（共105个端点）。我先为你验证API密钥。」
  2. 按照上述步骤解析API密钥。如果密钥缺失或为占位符，在此停止，先向用户索要密钥再继续。
  3. 告知用户将发起一次消耗1信用点的测试调用，然后运行：
    bash
    curl -s -H "x-api-key: KEY" "https://www.socialcrawl.dev/v1/tiktok/profile?handle=tiktok"
    （将
    KEY
    替换为解析到的密钥值。）
  4. 如果调用成功，确认密钥可用并展示剩余信用点，再回应用户的实际需求。
  5. 如果调用失败，上报错误并协助排查（见下方错误处理）。

Platforms

支持平台

PlatformEndpointsReference
TikTok24references/tiktok.md
Instagram12references/instagram.md
YouTube11references/youtube.md
Facebook12references/facebook.md
Twitter/X6references/twitter.md
LinkedIn6references/linkedin.md
Reddit7references/reddit.md
Threads5references/threads.md
Pinterest4references/pinterest.md
Google4references/google.md
Truth Social3references/truthsocial.md
Twitch2references/twitch.md
Snapchat1references/snapchat.md
Kick1references/kick.md
Amazon1references/amazon.md
Linktree1references/linktree.md
Linkbio1references/linkbio.md
Linkme1references/linkme.md
Komi1references/komi.md
Pillar1references/pillar.md
Utility1references/utility.md
平台端点数量参考文档
TikTok24references/tiktok.md
Instagram12references/instagram.md
YouTube11references/youtube.md
Facebook12references/facebook.md
Twitter/X6references/twitter.md
LinkedIn6references/linkedin.md
Reddit7references/reddit.md
Threads5references/threads.md
Pinterest4references/pinterest.md
Google4references/google.md
Truth Social3references/truthsocial.md
Twitch2references/twitch.md
Snapchat1references/snapchat.md
Kick1references/kick.md
Amazon1references/amazon.md
Linktree1references/linktree.md
Linkbio1references/linkbio.md
Linkme1references/linkme.md
Komi1references/komi.md
Pillar1references/pillar.md
Utility1references/utility.md

Workflow

工作流程

Determine what the user wants, then follow the matching workflow:
User wants data:
  1. Identify the platform and resource from their request
  2. Read the platform's reference file from the table above
  3. Resolve API key
  4. Construct and execute the curl command
  5. Return raw JSON response
  6. Note 
    credits_used
    and 
    credits_remaining
    from the response
User wants code:
  1. Identify platform, resource, and target language
  2. Read the platform's reference file
  3. Generate a working code snippet using 
    $SOCIALCRAWL_API_KEY
    env var for the key
  4. Present the code without executing
User asks about capabilities:
  1. Answer from the platform table above
  2. If they need details about auth, response format, errors, or credits, read references/api-overview.md
User asks about credits/balance:
  1. Resolve API key
  2. Run: 
    curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" "https://www.socialcrawl.dev/api/credits/balance"
  3. Return the balance
Ambiguous platform: If the user says "get profile for @nike" without specifying a platform, ask which platform they mean.
Multi-platform requests: Load each platform's reference file and make sequential calls.
先判断用户需求，再遵循对应的工作流程：
用户需要获取数据：
  1. 从用户请求中识别目标平台和资源
  2. 查阅上方表格中对应平台的参考文档
  3. 解析API密钥
  4. 构造并执行curl命令
  5. 返回原始JSON响应
  6. 标注响应中的
    credits_used
    和
    credits_remaining
用户需要生成代码：
  1. 识别目标平台、资源和目标编程语言
  2. 查阅对应平台的参考文档
  3. 生成可运行的代码片段，使用
    $SOCIALCRAWL_API_KEY
    环境变量传递密钥
  4. 展示代码无需执行
用户询问功能相关问题：
  1. 参考上方平台列表作答
  2. 如果用户需要了解认证、响应格式、错误或信用点相关的细节，查阅references/api-overview.md
用户询问信用点/余额：
  1. 解析API密钥
  2. 运行：
    curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" "https://www.socialcrawl.dev/api/credits/balance"
  3. 返回余额结果
平台不明确： 如果用户仅提到「获取@nike的资料」没有指定平台，询问用户目标平台。
多平台请求： 加载每个平台的参考文档并按顺序发起调用。

Making API Calls

发起API Calls

Base URL: 
https://www.socialcrawl.dev
All endpoints are GET requests:
curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  "https://www.socialcrawl.dev/v1/{platform}/{resource}?{param}={value}"
URL-encode parameter values that contain spaces or special characters.
基础URL：
https://www.socialcrawl.dev
所有端点均为GET请求：
curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  "https://www.socialcrawl.dev/v1/{platform}/{resource}?{param}={value}"
包含空格或特殊字符的参数值需要进行URL编码。

Credit Tiers

信用点等级

TierCostTypical endpoints
standard1 creditProfiles, posts, search, comments
advanced5 creditsAudience demographics, ad libraries, trending
premium10 creditsVideo transcripts, AI analysis
Before executing an advanced or premium call, mention the credit cost to the user. After every call, report 
credits_used
and 
credits_remaining
from the response.
等级消耗典型端点
standard1信用点资料、帖子、搜索、评论
advanced5信用点受众人群统计、广告库、趋势数据
premium10信用点视频字幕、AI分析
执行advanced或premium调用前，需告知用户对应的信用点消耗。每次调用结束后，上报响应中的
credits_used
和
credits_remaining
。

Error Handling

错误处理

CodeStatusAction
MISSING_API_KEY401Ask user for their API key
INVALID_API_KEY401"Your API key appears invalid. Check your SocialCrawl dashboard."
INSUFFICIENT_CREDITS402"You're out of credits. Top up at socialcrawl.dev/dashboard/billing"
INVALID_REQUEST400Check required params in the platform reference file
ENDPOINT_NOT_FOUND404"That endpoint doesn't exist. Check the platform table above."
RESOURCE_NOT_FOUND404"That profile/post wasn't found on the platform."
CONCURRENCY_LIMIT429"Too many concurrent requests. Wait a moment and retry."
UPSTREAM_ERROR502"Platform temporarily unavailable. Credits were refunded."
SERVICE_UNAVAILABLE503"Platform circuit breaker is open. Try again in 30s. Credits refunded."
INTERNAL_ERROR500"Unexpected error. Credits were refunded."
错误码状态码处理措施
MISSING_API_KEY401向用户索要API密钥
INVALID_API_KEY401「你的API密钥无效，请在SocialCrawl控制台检查。」
INSUFFICIENT_CREDITS402「你的信用点已用完，可前往 socialcrawl.dev/dashboard/billing 充值。」
INVALID_REQUEST400检查平台参考文档中的必填参数
ENDPOINT_NOT_FOUND404「该端点不存在，请参考上方平台列表。」
RESOURCE_NOT_FOUND404「对应平台上未找到该资料/帖子。」
CONCURRENCY_LIMIT429「并发请求过多，请稍候重试。」
UPSTREAM_ERROR502「平台暂时不可用，信用点已退还。」
SERVICE_UNAVAILABLE503「平台断路器已触发，请30秒后重试，信用点已退还。」
INTERNAL_ERROR500「发生未知错误，信用点已退还。」

References

参考文档

  • references/api-overview.md — Read when user asks about authentication, response format, error details, credit system, or the 
    ?format=raw
    parameter
  • references/{platform}.md — Read the specific platform file when user asks about or wants to call that platform's endpoints
  • references/api-overview.md — 用户询问认证、响应格式、错误详情、信用体系或
    ?format=raw
    参数时查阅
  • references/{platform}.md — 用户询问或需要调用对应平台的端点时，查阅特定平台的文档