# Cohorts (/docs/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](/docs/idempotency.md)). ```bash title="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}' ``` ```json title="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. ```bash title="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}' ``` ```json title="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. ```bash title="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 - [Cohorts reference](/docs/cohorts.md): Every field, the platforms, matching rules, errors and a 10,000-account walkthrough. - [Listening](/docs/engines/listening.md): Watch a topic across everyone instead of a list you chose. - [Idempotency](/docs/idempotency.md): Why cohort calls carry a key and how to retry safely.