Docs·Segments
PUT
/api/v1/spreelytics/cohorts/:cohortIdUpdate a segment
Changes a segment. Send only what changes: name, description or definition, which replaces the old one whole and is checked as on create. Every chart, dashboard and filter that uses the segment follows the new definition straight away, since membership is always worked out live.
It answers 404 when the id is not a segment in this audience. Needs the Editor or Admin role in the workspace that owns the audience. A Viewer gets 403.
Keys: an account key. Getting started explains both kinds.
Parameters
| Prop | In | Type | Notes |
|---|---|---|---|
cohortId | path | string | The segment id. |
contactListId | query | string | The audience id, a UUID. With an audience key it must be that key's own audience. |
Request body
| Prop | Type | Notes |
|---|---|---|
name? | string | Optional. Trimmed, and a blank name answers 400. |
description? | string | Optional. null or an empty string clears it. |
definition? | PeopleQueryRequestDto | Optional. A whole new definition, as on create. |
Response
| Prop | Type | Notes |
|---|---|---|
id | string | The segment id. Use it in a chart filter (inCohort), a cohort series or the analytics cohort_id filter. |
name | string | The segment name. |
description | string | The description, or null when there is none. |
definition | PeopleQueryRequestDto | The people-query exactly as saved. Send it to POST /people/query to count the members, or to POST /people/query/members to list them. |
createdAt | string | When it was created. Only the create call answers in ISO 8601 (2026-09-30T09:00:00.000Z). Every other call returns the database form (2026-09-30 09:00:00+00), so parse both. |
updatedAt | string | When it last changed. Create and update calls answer in ISO 8601, lists and reads in the database form, as with createdAt. |
Request
curl -X PUT 'https://app.spreelytics.com/api/v1/spreelytics/cohorts/:cohortId?contactListId=…' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ … }'
const res = await fetch('https://app.spreelytics.com/api/v1/spreelytics/cohorts/:cohortId', {
method: 'PUT',
headers: {
Authorization: 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({ /* see Request body above */ }),
});
const data = await res.json();
import requests
res = requests.put(
"https://app.spreelytics.com/api/v1/spreelytics/cohorts/:cohortId",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={}, # see Request body above
)
data = res.json()
Response
{
"id": "string",
"name": "string",
"description": "string",
"definition": {
"conditions": [
{
"source": "internal",
"kind": "revenue",
"event": "string",
"minAmount": 0,
"minCount": 0,
"countOp": "gte",
"propertyFilters": [
null
],
"property": "string",
"propertyOp": "is",
"values": [
null
],
"timeframe": {
"type": null,
"value": null,
"start": null,
"end": null
}
}
],
"match": "all",
"breakdown": "channel",
"startDate": "string",
"endDate": "string"
},
"createdAt": "string",
"updatedAt": "string"
}