SocialCrawl
Engines

Cohorts

Upload a list of public social accounts, then ask which of them posted about your keywords, with every step except the query free

A cohort answers a narrow question: which of these specific accounts talked about it? You upload a list of public accounts you already chose, such as a customer panel or a creator roster. Then you ask about keywords in a recent window. Cohorts does not find people. It reads the public posts of the ones you name.

Check the first call for free

Create the cohort with dry_run=1 first. It validates the request, creates nothing and costs 0 credits. Every cohort call that creates or uploads needs an Idempotency-Key header with a UUID, even on a dry run (Idempotency).

cURL
curl -X POST "https://www.socialcrawl.dev/v1/cohorts?dry_run=1" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: 11111111-1111-4111-8111-111111111111" \
  -H "Content-Type: application/json" \
  -d '{"name": "August purchaser panel", "retention_days": 30}'
Response
{
  "success": true,
  "platform": "cohorts",
  "endpoint": "/v1/cohorts",
  "data": {
    "valid": true,
    "normalized_params": { "name": "August purchaser panel", "retention_days": 30 },
    "estimate": { "hold": 0, "expected_min": 0, "expected_max": 0, "unit": "credits" }
  },
  "credits_used": 0
}

retention_days is 7 to 90. When it ends, the cohort and everything under it is deleted.

Create it and upload members

Send the same body without dry_run. Creating a cohort is free.

cURL
curl -X POST "https://www.socialcrawl.dev/v1/cohorts" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: 11111111-1111-4111-8111-111111111111" \
  -H "Content-Type: application/json" \
  -d '{"name": "August purchaser panel", "retention_days": 30}'
Response (trimmed)
{
  "success": true,
  "data": {
    "id": "Hk3vQ8mZr2LpWd5NxT9aB",
    "name": "August purchaser panel",
    "retention_days": 30
  },
  "credits_used": 0
}

Upload the accounts with PUT /v1/cohorts/{cohortId}/members, up to 1,000 per call and 10,000 per cohort. Each member is a platform, a handle and your own external_id, which comes back on every match so you can join results to your records. Anything else you know about these people stays on your side. Uploads are free.

Price a query

Ask the question with POST /v1/cohorts/{cohortId}/queries and add dry_run=1. All three caps are required and none has a default.

cURL
curl -X POST "https://www.socialcrawl.dev/v1/cohorts/Hk3vQ8mZr2LpWd5NxT9aB/queries?dry_run=1" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: 33333333-3333-4333-8333-333333333333" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": ["acme", "acme pro"],
    "date_from": "2026-08-01T00:00:00.000Z",
    "max_pages_per_identity": 3,
    "max_items_per_identity": 100,
    "max_credits": 30000
  }'

The dry run checks your body and your cohort, reserves nothing and quotes up to your max_credits. The real call reserves a ceiling sized to the cohort's members and page caps. It is refused free if that ceiling is above max_credits.

What does it cost?

Every call except the query costs 0 credits. The query reserves its worst case, then charges only for pages that succeeded. Failed, timed-out, cancelled and skipped pages cost nothing, and the unused reservation is refunded when the query ends. A page costs 1 credit on most platforms, 5 on LinkedIn, and 2 for each round on Instagram and YouTube.

How do you read the results?

Send the query without dry_run. It answers 202 at once with a query_id. Poll GET /v1/cohort-queries/{queryId}, then read GET /v1/cohort-queries/{queryId}/results for the matching posts per member. Both are free. Coverage is recorded for every member, including the ones that matched nothing.

Next steps

On this page