SocialCrawl

Use SocialCrawl with n8n

Pull social media data into n8n without writing a server.

You can call SocialCrawl from any n8n workflow today with the built-in HTTP Request node. One GET request with your key in the x-api-key header returns structured data from any of 95 platforms. Setup takes four steps.

Before you start

You need an n8n instance, self-hosted or cloud, and an API key from socialcrawl.dev under Dashboard, then API Keys. New accounts start with 100 free credits. The key goes into an n8n credential, never into a node field you share.

Prove the key with a call that costs nothing:

Check the key (0 credits)
curl "https://www.socialcrawl.dev/v1/credits/balance" \
  -H "x-api-key: sc_your_key_here"

A reply with "success": true and your balance in data.balance means the key works. You can also point an HTTP Request node at the same URL to test a credential.

Connect

Store your key as a credential

Create a Header Auth credential. Set the header name to x-api-key and the value to your key, which looks like sc_.... A credential keeps the key out of the workflow JSON and out of execution logs. A key typed into the Headers table does not get that protection.

Add an HTTP Request node

Set four fields:

FieldValue
MethodGET
URLhttps://www.socialcrawl.dev/v1/tiktok/profile (swap in any platform and resource)
Query parametersThe endpoint's inputs, for example handle = charlidamelio
AuthenticationThe Header Auth credential from the previous step

What can you call?

Every platform returns the same response shape, so one HTTP Request node handles TikTok, Instagram, YouTube, LinkedIn, Amazon and the rest. Only the URL and the query parameters change.

Workflow shapePathNotes
One profile, post, or listing/v1/{platform}/{resource}The everyday case. Browse the platform directory.
One query across many sources/v1/search/everywhereUniversal search in one request.
Many URLs or ids in one executionBatch endpointsOne request instead of one node execution per item.
Key check, no spend/v1/credits/balanceAlways free, so it is the safe way to validate a credential.

Read the answer

The node returns the whole response, so later nodes can read data, credits_used and credits_remaining directly.

Response
{
  "success": true,
  "platform": "tiktok",
  "endpoint": "/v1/tiktok/profile",
  "data": {
    "author": { "username": "charlidamelio", "followers": 155000000 },
    "computed": { "engagement_rate": 0.082, "language": "en" }
  },
  "credits_used": 1,
  "credits_remaining": 99,
  "request_id": "req-abc123",
  "cached": false
}

A list puts its rows in data.items. To fetch the next page, send pagination.next_cursor back as the cursor query parameter, and stop when pagination.has_more is false. See Pagination.

When it stops

An answer with success: false uses the same shape. Add an IF node on {{ $json.success }} before anything that reads data, and send the false branch somewhere you will see it.

Response
{
  "success": false,
  "error": {
    "type": "RESOURCE_NOT_FOUND",
    "message": "Profile not found for handle 'nosuchuser'.",
    "status": 404,
    "doc_url": "https://www.socialcrawl.dev/docs/errors#resource-not-found",
    "retryable": false
  },
  "credits_used": 0,
  "credits_remaining": 99,
  "request_id": "req-abc123"
}

By default the HTTP Request node fails on any answer that is not 2xx, and that stops the workflow. Two settings keep the answer instead. Open the node's Options, add Response, and turn on Never Error, so the body flows on to the IF node. Or set On Error to Continue (using error output), which sends the error information down a second output.

When your credits run out, the answer is a 402 with error.type set to INSUFFICIENT_CREDITS. Read error.message for the text and error.details.checkout_url for the link that opens checkout. When the link is absent, error.details.top_up_url opens the billing page. Pass both to a Send Email or Slack node so the owner sees them.

Never retry a 402, because it fails until credits are added. Retry a 429 after the seconds in the Retry-After header, and a 502, 503 or 504 after a short backoff. error.type names the cause and error.doc_url links the fix. See Errors.

What a run costs

It depends on the endpoint. Endpoint pricing lists each one, and Credits explains cache hits (0 credits) and refunds. GET /v1/utility/estimate quotes a call for 0 credits.

Read credits_used and credits_remaining from the JSON, or the X-Credits-Used and X-Credits-Remaining headers. A streamed response has no JSON body, so read its spend from the terminal done event.

Is there a dedicated node?

Not yet. A SocialCrawl community node, n8n-nodes-socialcrawl, is built but not published, neither on npm nor in the n8n community registry, so there is nothing to install today. The HTTP Request approach above is the supported path.

The node exposes one Resource per platform and one Operation per endpoint. The current build covers 39 platforms and 221 operations. Streaming endpoints are left out, because n8n's declarative routing cannot model them. Regeneration is manual, so the node trails the REST API by a release or more. It is usableAsTool, so an n8n AI Agent can call any endpoint it covers.

Once it publishes, you install it in two steps:

  1. In n8n, open Settings, then Community Nodes, and select Install. An instance owner has to enable community nodes first, and one-click verified install needs n8n v1.94.0 or newer.
  2. Enter the package name n8n-nodes-socialcrawl and install.

Until then the HTTP Request node covers every endpoint, including the ones the node will never carry.

Questions