# n8n (/docs/integrations/n8n) Pull social media data into n8n without writing a server. You can call SocialCrawl from any [n8n](https://n8n.io) 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](https://www.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: ```bash title="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: | Field | Value | | -------------------- | ----------------------------------------------------------------------------------- | | **Method** | `GET` | | **URL** | `https://www.socialcrawl.dev/v1/tiktok/profile` (swap in any platform and resource) | | **Query parameters** | The endpoint's inputs, for example `handle` = `charlidamelio` | | **Authentication** | The 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 shape | Path | Notes | | --------------------------------- | ------------------------------ | --------------------------------------------------------------- | | One profile, post, or listing | `/v1/{platform}/{resource}` | The everyday case. Browse the [platform directory](/platforms). | | One query across many sources | `/v1/search/everywhere` | [Universal search](/docs/search.md) in one request. | | Many URLs or ids in one execution | [Batch endpoints](/docs/batch.md) | One request instead of one node execution per item. | | Key check, no spend | `/v1/credits/balance` | Always 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. ```json title="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](/docs/pagination.md). ## 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. ```json title="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](/docs/errors.md). ## What a run costs It depends on the endpoint. [Endpoint pricing](/docs/endpoint-pricing.md) lists each one, and [Credits](/docs/credits.md) 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](/docs/streaming.md) 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 **Every request comes back unauthorized** The header name is `x-api-key`, not `Authorization`. Check that the Header Auth credential is attached to the node rather than pasted into the Headers table, and that the value has no trailing whitespace. Point a node at `/v1/credits/balance` to test a credential for free. **Downstream nodes fail on a missing field** They are reading `data` on an answer where `success` is `false`. Put an IF node on `{{ $json.success }}` before anything that touches `data`, and send the false branch to a notification or an error workflow. **The workflow hits 429 on a schedule** You are over the per-key request rate. Wait the `Retry-After` seconds before retrying, and stagger schedules across workflows that share one key. See [Rate limits](/docs/rate-limits.md). **A loop over hundreds of items is slow and expensive** One node execution per item is the wrong shape for bulk work. [Batch endpoints](/docs/batch.md) take many URLs or ids in a single request. For a listening workflow, [universal search](/docs/search.md) fans one query across 18 platforms in one call instead of one node per platform. **My key is visible in the execution log** The key was set inline in the Headers table. Move it to a Header Auth credential and run the workflow again. Credential values are redacted in the workflow JSON and in execution logs. - [Quickstart](/docs/quickstart.md): Your first authenticated request, start to finish. - [Batch endpoints](/docs/batch.md): Refresh hundreds of URLs in one request. - [Universal search](/docs/search.md): One query, many sources, one response. - [Skills & MCP](/docs/skills-and-mcp.md): Building an agent instead of a workflow? Start here.