OverviewPlatformsAPI Reference
Segments

Update a segment

Only the fields sent change. Pass the `groupId` the segment was saved in; a segment cannot move between scopes.

PATCH
/v1/segments/{id}

Authorization

AuthorizationBearer <token>

API key minted via POST /v1/api-keys (format mk_live_...)

In: header

Path Parameters

idstring

Segment id (seg_...).

Length1 <= length

Query Parameters

groupId?string

Scope to one keyword group (grp_...): only people who mentioned that group's keywords, with that group's own tags, notes, mute, merges, activities and segments. Omit for the whole workspace.

Length1 <= length

Request Body

name?string
Length1 <= length <= 80
description?string
Lengthlength <= 500
filter?

Replaces the whole filter.

Response Body

application/json

application/json

application/json

application/json

curl -X PATCH "https://api.mentio.dev/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"
    ]
  },
  "groupId": "string",
  "count": 0,
  "createdAt": "string",
  "updatedAt": "string"
}
{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "requestId": "string",
    "retryAfterSeconds": 0
  }
}
{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "requestId": "string",
    "retryAfterSeconds": 0
  }
}
{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "requestId": "string",
    "retryAfterSeconds": 0
  }
}

List segments GET

Your saved segments, each with the number of people in it right now (segments are evaluated on every read, never materialized), plus presets you can save as a starting point. Pass a segment id to GET /v1/people to list its members. With `groupId`, that keyword group's own segments, counted over its own people; without it, the workspace's. A segment belongs to one scope and is not visible from another.

Get the usage breakdown GET

What the workspace consumed and was charged over a window, grouped by one dimension per call (`by`: day, platform or keyword), in USD cents at list price, with the window's totals on every call. `range` reads a trailing window of UTC days ending today (default 30d); `month` reads one calendar month (YYYY-MM), the shape a bill or a per-customer margin is reconciled against. Keyword-days come from the daily tick and mention charges from the matches that billed, so a deleted keyword keeps its charges in the keyword rows (`keyword.removed`) while its mention counts read 0; the same numbers ride on each keyword as `stats.cost` for the running month. `totals.ledgerDebitCents` is what the wallet has debited so far for the window's days: mentions settle the morning after their day, so a window ending today lags `totals.totalCents` by the unsettled ones, and a closed month differs from it only by cumulative rounding. Rows are paged (`limit`, `offset`, `total`); a workspace may read this at most 30 times a minute through its keys and tokens together.