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 -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}'{
"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 -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}'{
"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 -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.
