---
title: "Create Segment"
method: POST
path: "/segments"
tags: ["Segments"]
---

# Create Segment

`POST /segments`

Create a custom user segment based on filter rules. Available on all plans, limited by your plan's `maxCustomSegments` quota.

After creation, segment membership is computed asynchronously. The segment will be available immediately but member counts may take a few moments to populate.

## Request body

- CreateSegmentRequest
  - `name` string — Segment name. If omitted, an auto-generated name will be assigned.
  - `description` string — A description of the segment purpose.
  - `icon` string — Icon identifier for the segment (e.g. "Users", "Tag").
  - `filters` object, required — Filter configuration defining segment membership.
    - `rules` union[], required — Array of filter rules. At least one rule is required.
      - union — A filter rule defining segment membership criteria.
        - object
          - `type` 'analysis', required — Rule based on conversation analysis metrics.
          - `field` 'sentiment' | 'frustration' | 'struggle' | 'commercialIntent' | 'cqi' | 'rating', required — The analysis metric to filter on.
          - `operator` 'gt' | 'lt' | 'eq' | 'gte' | 'lte', required — Comparison operator.
          - `value` number, required — Threshold value for the metric (0-1 scale for most metrics).
        - object
          - `type` 'analysis_flag', required — Rule based on detected flags.
          - `field` 'jailbreakDetected' | 'hallucinationDetected' | 'userToxicityDetected' | 'modelToxicityDetected' | 'userBiasDetected' | 'modelBiasDetected' | 'missingCapabilityDetected', required — The flag to filter on.
          - `value` boolean, required — Whether the flag should be true or false.
        - object
          - `type` 'property', required — Rule based on user properties.
          - `key` string, required — The property key (alphanumeric, dots, hyphens, underscores).
          - `operator` 'eq' | 'neq' | 'contains' | 'gt' | 'lt', required — Comparison operator.
          - `value` union, required — Value to compare against.
            - string
            - number
            - boolean
        - object
          - `type` 'conversation_property', required — Rule based on conversation-level properties.
          - `key` string, required — The conversation property key.
          - `operator` 'eq' | 'neq' | 'contains' | 'gt' | 'lt', required — Comparison operator.
          - `value` union, required — Value to compare against.
            - string
            - number
            - boolean
        - object
          - `type` 'conversation_count', required — Rule based on number of conversations.
          - `operator` 'gte' | 'lte', required — Comparison operator.
          - `value` integer, required — Conversation count threshold.
        - object
          - `type` 'last_seen', required — Rule based on when the user was last active.
          - `operator` 'within' | 'before', required — Time comparison operator.
          - `value` string, required — Time duration (e.g. "7d", "24h", "30m").
    - `productIds` string[] — Scope the segment to specific product IDs.
    - `dateRange` object — Optional date range filter.
      - `preset` '7d' | '30d' | '90d' | 'all' — Preset date range.
      - `from` string — Start date (ISO 8601).
      - `to` string — End date (ISO 8601).

## Response `201`

Segment created successfully

- CreateSegmentResponse
  - `id` string, uuid, required — The created segment ID.
  - `name` string, required — The segment name.
  - `type` 'custom', required — Always "custom" for API-created segments.
  - `description` string, nullable, required — Segment description.
  - `icon` string, nullable, required — Icon identifier.
  - `filters` object, required — The filter configuration.
  - `createdAt` string, date-time, required — When the segment was created.
  - `updatedAt` string, date-time, required — When the segment was last updated.

## Other responses

- `400` — Bad request - validation error
- `403` — Segment limit reached
- `500` — Server error

## Changes

- **2026-05-01** `f52e699d4abf` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/greenflash-ai/apis/greenflash-api-reference/changes/segments/post.md)

---

[API](https://skmtc.dev/greenflash-ai/apis/greenflash-api-reference.md) · [All operations](https://skmtc.dev/greenflash-ai/apis/greenflash-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/greenflash-ai/greenflash-api-reference/revisions/c566e560677d/schema)