---
title: "Upload cohort members"
method: PUT
path: "/cohorts/{cohortId}/members"
tags: ["cohorts"]
---

# Upload cohort members

`PUT /cohorts/{cohortId}/members`

## Request

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

Upserts one chunk of 1-1,000 members; a cohort holds at most 10,000. Re-sending the same `external_id` updates its identity without growing the count. Supported platforms: bluesky, instagram, kwai, linkedin, threads, tiktok, truth-social, twitch, twitter, youtube.

## Path parameters

- `cohortId` string, required

## Headers

- `Idempotency-Key` string, uuid, required

## Request body

- object
  - `members` object[], required
    - `external_id` string: Your own opaque identifier, echoed back on every match and coverage record. Never sent upstream.
    - `handle` string, required: Public handle, profile URL, or channel ID for this platform.
    - `platform` 'bluesky' | 'instagram' | 'kwai' | 'linkedin' | 'threads' | 'tiktok' | 'truth-social' | 'twitch' | 'twitter' | 'youtube', required

## Response `200`

Member upload applied

- object
  - `cached` boolean
  - `credits_remaining` integer, nullable
  - `credits_used` integer
  - `data` object
    - `inserted` integer
    - `member_count` integer
    - `unchanged` integer
    - `updated` integer
  - `endpoint` string
  - `platform` string
  - `request_id` string
  - `success` boolean

## Other responses

- `400`: Invalid request - missing or malformed parameters
- `401`: Unauthorized - missing or invalid API key
- `404`: Not found - the endpoint does not exist, or the requested resource was not found upstream
- `405`: Method not allowed - wrong HTTP verb for this endpoint
- `409`: Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation
- `413`: Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling
- `422`: Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)
- `429`: Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.
- `500`: Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit

---

[API](https://skmtc.dev/socialcrawl/apis/socialcrawl-api.md) · [All operations](https://skmtc.dev/socialcrawl/apis/socialcrawl-api/llms.txt) · [OpenAPI document](https://skmtc.dev/socialcrawl/apis/socialcrawl-api/revisions/a0ad2511004a?raw)