# n8n (/docs/n8n)

Pull social media, commerce, and review data into any n8n workflow with the SocialCrawl API

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 68 platforms.

  A dedicated SocialCrawl community node is built but **not published yet**,
  neither on npm nor in the n8n community registry. The HTTP Request approach
  below is the supported path today.

## Prerequisites

- An n8n instance, self-hosted or cloud.
- An API key from [socialcrawl.dev](https://www.socialcrawl.dev), under Dashboard → API Keys. New accounts start with 100 free credits.
- The `/v1/{platform}/{resource}` path for the data you want. Browse the [platform directory](/platforms) to find it.

## How do I use SocialCrawl in n8n right now?

### 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 (it looks like `sc_...`). Attaching a credential keeps the key out of the workflow JSON and out of execution logs, which an inline header does not.

### Add an HTTP Request node

Configure 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                                   |

### Read the envelope downstream

The node returns the full SocialCrawl envelope, 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
}
```

### Branch on failure

Errors use the same envelope with `success: false`, so add an **IF** node on `{{ $json.success }}` and route the false branch somewhere you will see it.

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

`error.type` is machine-readable and `error.doc_url` links to the exact fix. See [Errors](/docs/errors.md).

## What can you call?

Every platform returns the same envelope, so one HTTP Request node handles TikTok, Instagram, YouTube, LinkedIn, Amazon, and the rest. Only the URL and 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.    |

## Is there a dedicated SocialCrawl node?

Yes, and it is built. `n8n-nodes-socialcrawl` exposes one **Resource** per platform and one **Operation** per endpoint, generated from the SocialCrawl endpoint registry. The current build covers **39 platforms and 221 operations**; streaming (SSE) endpoints are excluded because n8n's declarative routing cannot model them. Regeneration is a manual step, so the node trails the REST API by a release or more. It is `usableAsTool`, so an n8n AI Agent can call any SocialCrawl endpoint it covers as a tool.

It is not published yet, so there is nothing to install today. Once it publishes, installation will be two steps:

1. In n8n, open **Settings → 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.

After that, add the **SocialCrawl** node, pick a **Resource** (a platform, or Universal Search), pick an **Operation** (an endpoint), and fill in the fields. Until then, the HTTP Request approach above covers every endpoint, including the ones the node will never carry.

## What does it cost?

Credits are billed exactly as the REST API bills them: most endpoints are 1 credit, heavier ones 5 or 10, and composite or bundle endpoints carry their own price (`search/everywhere` is a flat 20). Cache hits cost 0 credits. Empty results and upstream errors are auto-refunded. See [Endpoint pricing](/docs/endpoint-pricing.md) for the exact figure per endpoint, [Credits](/docs/credits.md) for how the ledger works, or [Pricing](/pricing) for credit packs.

Read `credits_used` and `credits_remaining` from the JSON envelope, or the `X-Credits-Used` and `X-Credits-Remaining` response headers. A [streamed response](/docs/streaming.md) has no envelope, so read its spend from the terminal `done` event instead.

## Troubleshooting

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.

They are reading `data` on a response where `success` is `false`. Add an IF node on `{{ $json.success }}` before anything that touches `data`, and route the false branch to a notification or an error workflow.

You are over the per-key request rate. Honour the `Retry-After` response header before retrying, and stagger schedules across workflows that share one key. See [Rate limits](/docs/rate-limits.md).

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 15 platforms in a single call instead of a node per platform.

The key was set inline in the Headers table. Move it to a Header Auth credential and re-run: credential values are redacted in the workflow JSON and in execution logs.

## Next steps

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