OverviewPlatformsAPI Reference
Segments

Update a segment

Changes a segment's name, description or filter. A new filter replaces the old one completely.

PATCH
/v1/segments/{id}

Authorization

bearerAuth
AuthorizationBearer <token>

An API key from POST /v1/api-keys. Keys start with ref_.

In: header

Path Parameters

id*string

The segment's id (seg_...).

Length1 <= length

Request Body

application/json

Fields you leave out stay as they are.

Response Body

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/segments/seg_abc123" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "string",  "name": "string",  "description": "string",  "filter": {    "platforms": [      "bluesky"    ],    "tags": [      "string"    ],    "minFollowers": 0,    "maxFollowers": 0,    "minMentions": 1,    "minNegative": 1,    "intents": [      "string"    ],    "keywordKinds": [      "brand"    ],    "neverKeywordKinds": [      "brand"    ],    "notPlatforms": [      "bluesky"    ],    "notTags": [      "string"    ],    "notIntents": [      "string"    ],    "newSinceDays": 1,    "linkHosts": [      "string"    ],    "muted": true,    "stages": [      "not_contacted"    ],    "automated": true,    "ownerIds": [      "string"    ]  },  "count": 0,  "createdAt": "string",  "updatedAt": "string"}
Was this page helpful?

List segments

Returns your saved segments with the current number of people in each, plus presets you can save as a start. Segments are counted on each read and never stored as lists. To see who is in one, send its id to GET /v1/people.

Get the usage breakdown

Returns what the workspace used and was charged over a period, in US cents at list price. Each call groups rows by one `by` value, day, platform or keyword, and always includes the totals. `range` reads the past UTC days up to today (30d by default). `month` reads one calendar month (YYYY-MM), which is what you match against a bill or a per-client margin. Keyword-days come from the daily run and mention charges from billed matches. So a deleted keyword keeps its charges in the keyword rows (`keyword.removed`), while its mention counts show 0. Each keyword carries the same numbers for the current month as `stats.cost`. `totals.ledgerDebitCents` is what the balance has been debited so far for the period's days. Mentions settle the morning after, so a period ending today is below `totals.totalCents` by the unsettled ones, and a finished month differs only by cumulative rounding. Rows come in pages (`limit`, `offset`, `total`). A workspace can call this 30 times a minute across all its keys and tokens.