---
title: "List segments"
method: GET
path: "/v1/segments"
tags: ["Segments"]
---

# List segments

`GET /v1/segments`

## Request

- Base URL: `https://api.mentio.dev`
- URL: `https://api.mentio.dev/v1/segments`
- Auth: HTTP bearer

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.

## 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.

## Response `200`

Every segment, with presets

- object
  - `data` object[], required
    - `id` string, required: Segment id (seg_...).
    - `name` string, required
    - `description` string, required
    - `filter` object, required
      - `platforms` string[]: People with an account on any of these platforms.
      - `tags` string[]: People carrying any of these tags.
      - `minFollowers` integer: At least this many followers. Unknown reach never matches.
      - `maxFollowers` integer: At most this many followers. Unknown reach never matches.
      - `minMentions` integer: At least this many matched mentions.
      - `minNegative` integer: At least this many negative mentions.
      - `intents` string[]: At least one mention carrying any of these intents.
      - `keywordKinds` string[]: Mentioned a keyword of any of these kinds.
      - `neverKeywordKinds` string[]: Never mentioned a keyword of these kinds.
      - `notPlatforms` string[]: Nobody with an account on these platforms.
      - `notTags` string[]: Nobody carrying any of these tags.
      - `notIntents` string[]: Nobody whose mentions carry any of these intents.
      - `newSinceDays` integer: First seen within this many days.
      - `linkHosts` string[]: At least one mention linking to any of these hosts, the host itself or a subdomain of it.
      - `muted` boolean: true: only muted people; false: only unmuted.
      - `stages` string[]: People at any of these outreach stages.
      - `automated` boolean: true: only people whose matched posts are mostly machine-made (bot accounts); false: only the rest.
      - `ownerIds` string[]: People owned by any of these members (user ids); "none" matches people nobody owns.
    - `groupId` string, nullable, required: The group this segment belongs to, or null for a workspace segment.
    - `count` integer, required: People in the segment right now; it is evaluated on every read.
    - `createdAt` string, required: ISO 8601 timestamp, UTC.
    - `updatedAt` string, required: ISO 8601 timestamp, UTC.
  - `presets` object[], required: Starting points you can save with POST /v1/segments.
    - `key` string, required
    - `name` string, required
    - `description` string, required
    - `filter` object, required
      - `platforms` string[]: People with an account on any of these platforms.
      - `tags` string[]: People carrying any of these tags.
      - `minFollowers` integer: At least this many followers. Unknown reach never matches.
      - `maxFollowers` integer: At most this many followers. Unknown reach never matches.
      - `minMentions` integer: At least this many matched mentions.
      - `minNegative` integer: At least this many negative mentions.
      - `intents` string[]: At least one mention carrying any of these intents.
      - `keywordKinds` string[]: Mentioned a keyword of any of these kinds.
      - `neverKeywordKinds` string[]: Never mentioned a keyword of these kinds.
      - `notPlatforms` string[]: Nobody with an account on these platforms.
      - `notTags` string[]: Nobody carrying any of these tags.
      - `notIntents` string[]: Nobody whose mentions carry any of these intents.
      - `newSinceDays` integer: First seen within this many days.
      - `linkHosts` string[]: At least one mention linking to any of these hosts, the host itself or a subdomain of it.
      - `muted` boolean: true: only muted people; false: only unmuted.
      - `stages` string[]: People at any of these outreach stages.
      - `automated` boolean: true: only people whose matched posts are mostly machine-made (bot accounts); false: only the rest.
      - `ownerIds` string[]: People owned by any of these members (user ids); "none" matches people nobody owns.

## Other responses

- `401`: Missing or invalid API key
- `404`: No such group

---

[API](https://skmtc.dev/mentio/apis/mentio-api.md) · [All operations](https://skmtc.dev/mentio/apis/mentio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mentio/apis/mentio-api/revisions/b16a21d0ed02?raw)