socialcrawl（socialcrawl 搜索）

SocialCrawl API

Unified social media data API. One API key, one response format, 21 platforms, 108 endpoints. Author and Post responses are normalized through platform field maps and augmented with deterministic computed fields (engagement_rate, language, content_category, estimated_reach) under data.computed. List archetypes (PostList, CommentList, SearchResult, Audience, Analytics) pass through as {items, next_cursor?, total?} without computed fields. Add ?format=raw to bypass the transform pipeline entirely.

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: 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).

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: 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).

Platforms

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/v1/credits/balance"
3. Return data.balance from the envelope (the call costs 0 credits)

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.

Making 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.

Parameter rules

• Required params — each platform reference file lists the required query parameters for every endpoint. A request missing any of them returns 400 INVALID_REQUEST with the message Missing required parameter(s):...; no credit is deducted.
• oneOf groups — some endpoints (notably on YouTube, Facebook, TikTok, Instagram, Reddit, Google, Truth Social) accept mutually-substitutable identifiers such as channelId / handle / url. Pass at least one member of the group; the platform reference file lists the valid choices.
• Optional params — any non-required param listed in the reference file may be forwarded. Anything unrecognized is rejected upstream.
• format=raw — disables field maps and computed fields so you receive the original ScrapeCreators JSON.

Credit Tiers

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.

Free calls (0 credits deducted):

• Cache hits — cached: true + X-Cache: HIT. Same data, no charge.
• Idempotent replays — X-Idempotent-Replay: true. See "Idempotent Retries" below.
• Empty-upstream 404s — when upstream returns a 200 with an empty body (nonexistent profile/post), the credit is auto-refunded and you get RESOURCE_NOT_FOUND.
• GET /v1/credits/balance — meta endpoint.
• Pre-flight rejections — 400/401/402/405/409/422/404-endpoint-not-found never deduct.

Idempotent Retries

Any /v1/* call can be made safe to retry by sending an Idempotency-Key header (UUIDv4 or any opaque 16+ char string). Replays of the same key + same params return the original body verbatim with X-Idempotent-Replay: true and 0 credits deducted. Keys last 24h. Reusing the key with different params returns 422; a key owned by a different account returns 409.

curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  -H "Idempotency-Key: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" \
  "https://www.socialcrawl.dev/v1/tiktok/profile?handle=tiktok"

Response Headers

Warnings Channel

Successful responses may include an optional data._warnings: string[] with advisory notices from the transform pipeline (e.g. a clamped engagement_rate > 1.0, or an unresolved field-map path). Treat as observability-only — do not gate logic on it. Empty arrays are omitted.

Error Handling

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