Create test cohort

Deprecated. This page documents the v2 buyer API, which is closed to new API clients and switches off on 1 December 2026. Use V3 instead: see Move a v2 buyer REST integration to V3. The conversion endpoint, Log event, stays open.

POST /api/v2/buyer/advertisers/{advertiserId}/test-cohorts Creates a test cohort — a flexible audience definition (geo, segment, zip code, or custom) that fills one arm of an incrementality test. Incrementality tests compare a TREATMENT cohort against a matched CONTROL.

Request

curl -X POST https://api.apostra.com/api/v2/buyer/advertisers/12345/test-cohorts \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "West Coast Treatment Group",
    "description": "Users in CA, OR, WA receiving full ad exposure",
    "cohortType": "geographic",
    "role": "TREATMENT",
    "definition": {
      "type": "geo_region",
      "regions": ["US-CA", "US-OR", "US-WA"]
    },
    "estimatedSize": 50000
  }'

{
  "name": "Mountain West Control",
  "cohortType": "geographic",
  "role": "CONTROL",
  "definition": {
    "type": "geo_region",
    "regions": ["US-AZ", "US-NV", "US-NM"]
  },
  "estimatedSize": 48000
}

Parameters

Field	Type	Required	Notes
`advertiserId`	string	Yes	Path parameter — the owning advertiser
`name`	string	Yes	Cohort label (max 255)
`cohortType`	string	Yes	Free-form classification (e.g. `geographic`, `demographic`, `behavioral`)
`definition`	object	Yes	Targeting definition. `type` is required (`zip_code`, `user_segment`, `geo_region`, `custom`); additional fields vary by type
`description`	string	No	Free-text description (max 1000)
`role`	enum	No	`TREATMENT`, `CONTROL`, `OBSERVATION` (default `TREATMENT`)
`estimatedSize`	integer	No	Size estimate for power analysis

Response

{
  "id": "42",
  "advertiserId": "12345",
  "name": "West Coast Treatment Group",
  "description": "Users in CA, OR, WA receiving full ad exposure",
  "cohortType": "geographic",
  "role": "TREATMENT",
  "definition": { "type": "geo_region", "regions": ["US-CA", "US-OR", "US-WA"] },
  "estimatedSize": 50000,
  "isActive": true,
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-01-15T10:30:00Z"
}

The returned id is the cohortId you pass to Get, Update, and Delete.

Errors

400 VALIDATION_ERROR — missing name, cohortType, or definition.type, or invalid role.
404 NOT_FOUND — advertiserId does not exist or is not visible to the authenticated account.

See Errors for the full error contract.

Measurement tasks

All measurement operations

Measurement overview

Pipeline, belief state, and concepts

List test cohorts

See defined cohorts

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Create test cohort

Request

Parameters

Response

Errors

Measurement tasks

Measurement overview

List test cohorts

​Request

​Parameters

​Response

​Errors

​Related

Measurement tasks

Measurement overview

List test cohorts

Request

Parameters

Response

Errors

Related