SocialCrawl

Use SocialCrawl with Clay

Pull social media data into Clay without writing a server.

You can call SocialCrawl from a Clay table with an HTTP API column. One column calls one endpoint for every row. Setup takes three steps: save the key, add the column, map the result.

Before you start

Create an API key in the dashboard under API Keys. Clay's HTTP API column stores credentials in an account you select or create, so save the key there once and never type it into a cell. 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.

Connect

Add an HTTP API column. Clay asks for the request method, the endpoint URL, the authentication and any headers or query parameters. Set these:

FieldValue
MethodGET
URLhttps://www.socialcrawl.dev/v1/tiktok/profile
Queryhandle = a column holding the handle, for example charlidamelio
Headersx-api-key = your key, from the saved account

Use one column per job. A column that runs on every row of a long table makes one call per row.

Read the answer

Every response has the same shape. Branch on success, and read the rows from data. A list puts its rows in data.items, with pagination.next_cursor as the token for the next page.

Response (trimmed)
{
  "success": true,
  "data": { "author": { "username": "charlidamelio", "followers": 155000000 } },
  "credits_used": 1,
  "credits_remaining": 99
}

Pull single values out of the result with a path such as data.author.followers. See Pagination for lists.

When it stops

When credits run out, the answer is a 402 with error.type set to INSUFFICIENT_CREDITS. Read the response body in the cell: error.message holds the text and error.details.checkout_url holds the link that opens checkout. When the link is absent, error.details.top_up_url opens the billing page. Top up before you run the column again, or the same rows fail the same way.

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. See Errors.

What a run costs

It depends on the endpoint, and some endpoints are priced by what they return. Endpoint pricing lists each one, and Credits explains cache hits and refunds. A column over many rows multiplies the price of one call by the row count. GET /v1/utility/estimate quotes a call for 0 credits.

On this page