> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update test cohort

> Update the definition, role, or size of a test cohort

`PUT /api/v2/buyer/advertisers/{advertiserId}/test-cohorts/{cohortId}`

Updates an existing test cohort. All body fields are optional — send only what you want to change; omitted fields keep their current values.

## Request

<CodeGroup>
  ```bash curl theme={null}
  curl -X PUT https://api.apostra.com/api/v2/buyer/advertisers/12345/test-cohorts/cohort_abc123 \
    -H "Authorization: Bearer $SCOPE3_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "West Coast Treatment Group - Updated",
      "definition": {
        "type": "geo_region",
        "regions": ["US-CA", "US-OR", "US-WA", "US-NV"]
      },
      "estimatedSize": 62000
    }'
  ```
</CodeGroup>

## Parameters

| Field | Type | Required | Notes |
| - | - | - | - |
| `advertiserId` | string | Yes | Path parameter — the owning advertiser |
| `cohortId` | string | Yes | Path parameter — the cohort ID |
| `name` | string | No | Cohort label (max 255) |
| `description` | string | No | Free-text description (max 1000) |
| `cohortType` | string | No | Free-form classification |
| `role` | enum | No | `TREATMENT`, `CONTROL`, `OBSERVATION` |
| `definition` | object | No | Targeting definition. `type` is required; additional fields vary by type |
| `estimatedSize` | integer | No | Size estimate for power analysis |

## Response

```json theme={null}
{
  "id": "cohort_abc123",
  "advertiserId": "12345",
  "name": "West Coast Treatment Group - Updated",
  "description": null,
  "cohortType": "geographic",
  "role": "TREATMENT",
  "definition": { "type": "geo_region", "regions": ["US-CA", "US-OR", "US-WA", "US-NV"] },
  "estimatedSize": 62000,
  "isActive": true,
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-03-20T14:45:00Z"
}
```

Returns the full cohort after the update.

## Errors

* `400 VALIDATION_ERROR` — invalid `role` or a `definition` missing its `type`.
* `404 NOT_FOUND` — `cohortId` (or `advertiserId`) does not exist or is not visible to the authenticated account.

See [Errors](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Measurement tasks" href="/v2/buyer/measurement/tasks" icon="list-check">
    All measurement operations
  </Card>

  <Card title="Measurement overview" href="/v2/guides/measurement-incrementality" icon="chart-line">
    Pipeline, belief state, and concepts
  </Card>

  <Card title="Get test cohort" href="/v2/buyer/measurement/tasks/get-test-cohort" icon="magnifying-glass">
    Read the current cohort
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.