---
title: "List segments"
method: GET
path: "/api/v3/segments"
tags: ["V3 Segments"]
---

# List segments

`GET /api/v3/segments`

## Request

- Base URL: `https://app.formbricks.com`
- URL: `https://app.formbricks.com/api/v3/segments`
- Auth: one of:
  - API key in cookie `next-auth.session-token`
  - API key in header `x-api-key`
  - HTTP bearer

Returns a workspace's segments, searched, sorted and counted on the server. Private segments
(survey-local targeting drafts) are never listed. A segment's survey references — including the
`surveyIds` of its survey-interaction filters — only name surveys the caller may see. Requires the Contacts entitlement (**403** without it). The cursor is bound to
`sortBy` and `filter[title][contains]`; changing either while paging → **400** naming `cursor`. Unknown query
parameters → **400**. Session cookie, `x-api-key`, or a Bearer token.

## Query parameters

- `workspaceId` string, cuid2, required
- `limit` integer
- `cursor` string
- `includeTotalCount` boolean
- `filter[title][contains]` string
- `sortBy` '-updatedAt' | '-createdAt' | 'title'

## Response `200`

Segments retrieved successfully

- object
  - `data` SegmentResource[], required
    - `id` string, cuid2, required
    - `title` string, required
    - `description` string, nullable, required
    - `isPrivate` boolean, required: Always `false` in list results.
    - `filters` object[], required: Contact targeting filter tree. An empty array targets everyone. Each node joins the previous one via its `connector` (`and`/`or`; the first node's connector is null). A node's `resource` is either a single filter condition or a nested filter group (enabling parenthesized `and`/`or` logic).
      - `id` string, cuid2, required
      - `connector` 'and' | 'or' | 'null', nullable, required: Logical connector joining this node to the previous one. Null for the first node.
      - `resource` union, required: A single filter condition, or a nested filter group for grouped logic.
        - union: A single targeting condition. `root.type` selects the subject and determines the valid `qualifier.operator` set: `attribute` (a workspace contact-attribute key), `person` (a built-in person identifier such as `userId`/`email`), `segment` (membership in another segment), `device`, or `surveyInteraction` (how the contact interacted with surveys). Each variant is one member of this union; the matching member is chosen by `root.type`.
          - object: Matches on a workspace contact-attribute value.
            - `id` string, cuid2, required
            - `root` object, required
              - …
            - `qualifier` object, required
              - …
            - `value` union, required: Comparison value for a segment filter condition. A string or number for most operators; a relative-date object (`{ amount, unit }`) for `isOlderThan` / `isNewerThan`; a two-element `[from, to]` string array for `isBetween`. Ignored for `isSet` / `isNotSet` but still required.
              - …
          - object: Matches on a built-in person identifier.
            - `id` string, cuid2, required
            - `root` object, required
              - …
            - `qualifier` object, required
              - …
            - `value` union, required: Comparison value for a segment filter condition. A string or number for most operators; a relative-date object (`{ amount, unit }`) for `isOlderThan` / `isNewerThan`; a two-element `[from, to]` string array for `isBetween`. Ignored for `isSet` / `isNotSet` but still required.
              - …
          - object: Matches on membership in another segment.
            - `id` string, cuid2, required
            - `root` object, required
              - …
            - `qualifier` object, required
              - …
            - `value` union, required: Comparison value for a segment filter condition. A string or number for most operators; a relative-date object (`{ amount, unit }`) for `isOlderThan` / `isNewerThan`; a two-element `[from, to]` string array for `isBetween`. Ignored for `isSet` / `isNotSet` but still required.
              - …
          - object: Matches on the contact's device type.
            - `id` string, cuid2, required
            - `root` object, required
              - …
            - `qualifier` object, required
              - …
            - `value` union, required: Comparison value for a segment filter condition. A string or number for most operators; a relative-date object (`{ amount, unit }`) for `isOlderThan` / `isNewerThan`; a two-element `[from, to]` string array for `isBetween`. Ignored for `isSet` / `isNotSet` but still required.
              - …
          - object: Matches on how the contact interacted with surveys within a time window. `surveyIds` only names surveys the caller may see; ids of other surveys the segment targets are left out.
            - `id` string, cuid2, required
            - `root` object, required
              - …
            - `qualifier` object, required
              - …
            - `value` object, required
              - …
        - SegmentFilters (recursive)
    - `workspaceId` string, cuid2, required
    - `surveys` string[], required: Ids of the visible surveys this segment is attached to.
    - `activeSurveys` SegmentSurveyReference[], required: Visible attached surveys that are in progress.
      - `id` string, cuid2, required
      - `name` string, required
    - `inactiveSurveys` SegmentSurveyReference[], required: Visible attached surveys in any other status.
      - `id` string, cuid2, required
      - `name` string, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `meta` CountedListMeta, required: A list `meta` carrying pagination and the filtered total. `totalCount` is `required` but nullable, gated on the operation's `includeTotalCount` parameter.
    - `limit` integer, required: The page size actually applied. Carries no `maximum`: it echoes what the server used, it does not bound what may be asked for. The request-side bound is the `limit` query parameter on the operation itself and differs per collection — read it there. A shared description cannot state it without being wrong for some of the operations that compose this base.
    - `nextCursor` string, nullable, required: Opaque cursor for the next page. `null` when there are no more results — the only reliable end-of-collection signal, since the server may return fewer items than `limit` without the collection being exhausted. Pass it back verbatim: the encoding is deliberately unspecified and may change without notice, so a client that decodes or constructs one is relying on something this contract does not promise.
    - `totalCount` integer, nullable, required: Total number of items matching the current filters (and search) across all pages. `null` when the request did not ask for it — see the operation's `includeTotalCount` parameter, whose default differs per collection.

## Other responses

- `400`: Bad Request — malformed JSON, invalid query/body/params, duplicate name, or unsupported field.
- `401`: Not authenticated (no valid session or API key).
- `403`: Forbidden — no workspace access, or resource does not exist (404 not used; avoids existence leak).
- `429`: Rate limit exceeded.
- `500`: Internal Server Error.

## Changes

- **2026-10-29** `82c0afd2df39`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/formbricks/apis/formbricks-api-v3/changes/api/v3/segments/get.md)

---

[API](https://skmtc.dev/formbricks/apis/formbricks-api-v3.md) - [All operations](https://skmtc.dev/formbricks/apis/formbricks-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/formbricks/apis/formbricks-api-v3/revisions/25335c959a13?raw)