Sign in

v5

latestOpenAPI 3.0.3Apache 2.0raw.githubusercontent.com2026-02-283466592.5 MB
Segments

Create segment

Create a new segment.

post/api/v2/segments/{projectKey}/{environmentKey}

Path parameters

projectKeystring string required

The project key

The project key

environmentKeystring string required

The environment key

The environment key

Request body

namestring required

A human-friendly name for the segment

keystring required

A unique key used to reference the segment

descriptionstring

A description of the segment's purpose

tagsstring[]

Tags for the segment

unboundedboolean

Whether to create a standard segment (<code>false</code>) or a big segment (<code>true</code>). Standard segments include rule-based and smaller list-based segments. Big segments include larger list-based segments and synced segments. Only use a big segment if you need to add more than 15,000 individual targets.

unboundedContextKindstring

For big segments, the targeted context kind.

Example request

{
  "name": "Example segment",
  "key": "segment-key-123abc",
  "description": "Bundle our sample customers together",
  "tags": [
    "testing"
  ],
  "unboundedContextKind": "device"
}

Response

Segment response

namestring required

A human-friendly name for the segment.

descriptionstring

A description of the segment's purpose. Defaults to <code>null</code> and is omitted in the response if not provided.

tagsstring[] required

Tags for the segment. Defaults to an empty array.

creationDateinteger required
lastModifiedDateinteger required
keystring required

A unique key used to reference the segment

includedstring[]

An array of keys for included targets. Included individual targets are always segment members, regardless of segment rules. For list-based segments over 15,000 entries, also called big segments, this array is either empty or omitted.

excludedstring[]

An array of keys for excluded targets. Segment rules bypass individual excluded targets, so they will never be included based on rules. Excluded targets may still be included explicitly. This value is omitted for list-based segments over 15,000 entries, also called big segments.

_linksobject required

The location and content type of related resources

versioninteger required

Version of the segment

deletedboolean required

Whether the segment has been deleted

unboundedboolean

Whether this is a standard segment (<code>false</code>) or a big segment (<code>true</code>). Standard segments include rule-based segments and smaller list-based segments. Big segments include larger list-based segments and synced segments. If omitted, the segment is a standard segment.

unboundedContextKindstring

For big segments, the targeted context kind.

generationinteger required

For big segments, how many times this segment has been created.

_externalstring

The external data store backing this segment. Only applies to synced segments.

_externalLinkstring

The URL for the external data store backing this segment. Only applies to synced segments.

_importInProgressboolean

Whether an import is currently in progress for the specified segment. Only applies to big segments.

Example response

{
  "name": "Example segment",
  "description": "Bundle our sample customers together",
  "tags": [
    "testing"
  ],
  "key": "segment-key-123abc",
  "included": [
    "user-key-123abc"
  ],
  "excluded": [
    "user-key-123abc"
  ],
  "rules": [
    {
      "_id": "1234a56b7c89d012345e678f",
      "clauses": [
        {
          "_id": "12ab3c45de678910fab12345",
          "attribute": "email",
          "negate": false,
          "op": "endsWith",
          "values": [
            ".edu"
          ]
        }
      ]
    }
  ],
  "version": 1,
  "_access": {
    "denied": [
      {
        "reason": {
          "resources": [
            "proj/*:env/*;qa_*:/flag/*"
          ],
          "actions": [
            "*"
          ],
          "effect": "allow"
        }
      }
    ],
    "allowed": [
      {
        "reason": {
          "resources": [
            "proj/*:env/*;qa_*:/flag/*"
          ],
          "actions": [
            "*"
          ],
          "effect": "allow"
        }
      }
    ]
  },
  "_flags": [
    {
      "name": "Example flag",
      "key": "flag-key-123abc"
    }
  ],
  "_external": "amplitude",
  "_externalLink": "https://analytics.amplitude.com/org/1234/cohort/123abc"
}