cohorts

Submit a cohort keyword query

Submits an asynchronous keyword query over the cohort's recent authored activity. Returns 202 immediately with a poll URL. Credits are reserved at the worst-case ceiling on submission, metered one per successful upstream page, and the unspent remainder is refunded exactly once when the query reaches a terminal state.

post/cohorts/{cohortId}/queries

Request

  • Base URL: https://www.socialcrawl.dev/v1
  • URL: https://www.socialcrawl.dev/v1/cohorts/{cohortId}/queries
  • Auth: API key in header x-api-key

Path parameters

cohortIdstring required
Example:4MRtBDNO0stwfon8emOHT

Cohort identifier returned by POST /v1/cohorts.

Headers

Idempotency-Keystring uuid required

Required UUID that makes the mutation safely retriable. Replaying the same key with the same body returns the original resource with the X-Idempotent-Replay and Idempotent-Replayed headers; replaying it with a different body returns 422 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH.

Request body

date_fromstring date-time required

Start of the observation window as a full RFC3339 timestamp.

date_tostring date-time

Optional end of the observation window.

keywordsstring[] required

1-20 unique keywords, matched literally after Unicode normalization and case folding.

match'keywords' | 'topics' | 'both'

Optional. keywords (the default) is the literal keyword match. topics checks every keyword match against your topics and returns only the ones that are about a topic, which removes homonyms (a fruit under the keyword apple). both checks every authored item and returns an item when a keyword matches OR it is about a topic, which adds posts that never use your keywords. topics and both require topics. If an item cannot be checked, the keyword match stands and its matched_topics is null.

max_creditsinteger required

Your safety limit. Submission fails with 400 if the computed ceiling exceeds it; it is never permission to exceed the ceiling.

max_items_per_identityinteger required
max_pages_per_identityinteger required

Page budget per route. Exhausting it leaves window_complete false for that member.

platformsstring[]

Optional subset of the cohort's platforms to query. Defaults to every platform present in the cohort.

Example request

{
  "date_from": "2026-08-01T00:00:00.000Z"
}

Response

Query accepted

cachedboolean
credits_remaininginteger nullable
credits_usedinteger
endpointstring
platformstring
request_idstring
successboolean

Example response

{
  "platform": "cohorts",
  "success": true
}

Changes

No recorded changes to this operation across all 1 revision of this API.