> ## Documentation Index > Fetch the complete documentation index at: https://docs.formo.so/llms.txt > Use this file to discover all available pages before exploring further. # List Segments > Retrieve all audience segments for your project using the Formo API. Returns segment names and filters. ## OpenAPI ````yaml GET /v0/segments openapi: 3.1.0 info: title: Formo Public API description: >- REST API for managing Formo projects, analytics, alerts, boards, charts, contracts, segments, and AI chat. **Auth.** Every endpoint on `api.formo.so` requires a workspace API key with the appropriate scopes (see `x-api-scopes`). The one exception is `POST /v0/raw_events`, which runs on `events.formo.so` and authenticates with the project SDK write key instead. **Response shape.** Successful responses return the resource directly (or `{ data: [...], total, page, size, has_more }` for paginated lists). HTTP status carries success/failure; there is no envelope wrapping success bodies. **Errors.** Non-2xx responses from `api.formo.so` use the `Error` envelope, with two exceptions: some rate-limit rejections reply in plain text, and `POST /v0/raw_events` returns a plain `{ "error": "..." }` object. Treat the HTTP status as authoritative and parse defensively: `{ error: { code, message, doc_url, param?, details? } }`. Branch on the machine-readable `code` (see `ErrorCode` enum) and follow `doc_url` to the matching section of the [errors reference](https://docs.formo.so/api/errors). **Idempotency.** Pass an `Idempotency-Key` header on write requests to alerts, boards, charts, contracts, segments, and import to make retries safe; the response is cached for 24 h and replayed on duplicate keys. Profile writes and `POST /v0/query` do not support it. version: 0.1.0 contact: name: Formo url: https://formo.so servers: - url: https://api.formo.so description: API Server (boards, alerts, contracts, segments, profiles, query, import) - url: https://events.formo.so description: Events Server (event ingestion) security: - WorkspaceApiKey: [] tags: - name: Alerts description: Manage project alerts and notifications - name: Boards description: Manage dashboard boards - name: Charts description: Manage charts within boards - name: Contracts description: Manage blockchain contract monitoring - name: Segments description: Manage user segments - name: Profiles description: Wallet profiles and import - name: Query description: >- Execute SQL queries and call pre-built analytics endpoints (KPIs, top pages, lifecycle, retention, revenue). Requires the query:read scope. - name: Events description: Event ingestion API (events.formo.so) paths: /v0/segments: get: tags: - Segments summary: List segments description: List user segments for the project scoped to the API key. Paginated. operationId: listSegments parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Size' responses: '200': description: Paginated list of segments content: application/json: schema: allOf: - $ref: '#/components/schemas/PaginatedListMeta' - type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/Segment' example: data: - id: seg_e3f4g5h6i7j8 projectId: proj_abc123 title: High net worth desktop users filters: - field: device op: eq value: desktop - field: net_worth_usd op: gte value: '100000' page: 1 size: 100 total: 1 has_more: false components: parameters: Page: name: page in: query required: false schema: type: integer minimum: 1 default: 1 description: 1-indexed page number. Defaults to 1. Size: name: size in: query required: false schema: type: integer minimum: 1 maximum: 200 default: 100 description: Page size. Defaults to 100, capped at 200. schemas: PaginatedListMeta: type: object description: >- Pagination cursor returned alongside `data` on every paginated list endpoint. Use these to walk pages: `has_more` is true while `page * size < total`. Combine with the matching `Page` and `Size` query parameters to request the next page. required: - page - size - total - has_more properties: page: type: integer description: 1-indexed page number echoed from the request. size: type: integer description: Page size echoed from the request. total: type: integer description: Total row count across all pages. has_more: type: boolean description: True when more pages remain (`page * size < total`). Segment: type: object description: >- A saved segment. `filters` is an array of canonical filter objects combined with implicit AND. properties: id: type: string title: type: string projectId: type: string filters: type: array items: $ref: '#/components/schemas/SegmentFilterCondition' required: - id - title - filters SegmentFilterCondition: type: object additionalProperties: false description: >- A condition in a saved segment. Segment entries use the canonical `{field, op, value}` envelope and are combined with implicit AND. Nested event-property predicates are not supported by saved segments. properties: field: type: string minLength: 1 op: type: string enum: - eq - neq - gt - lt - gte - lte - in - nin - startsWith - endsWith - contains - notEmpty - isEmpty value: oneOf: - type: string - type: number - type: boolean - type: array minItems: 1 items: oneOf: - type: string pattern: ^[^|]*$ - type: number - type: 'null' description: >- Value to compare against. Omit for `notEmpty` and `isEmpty`. Membership arrays must be non-empty. Array string members cannot contain a literal `|`, which is reserved as the Tinybird membership separator. required: - field - op securitySchemes: WorkspaceApiKey: type: http scheme: bearer description: >- Workspace API key (e.g. `formo_xxx`). Create one in the Formo dashboard under Team Settings > API. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.