# Segments

> Part of the Cowliss docs. Markdown for every page: append `index.md` to its URL. Site map: /llms.txt

<!-- GENERATED by apps/docs/scripts/generate-api-reference.ts. Do not edit. Regenerate with `pnpm -F cowliss-docs generate`. -->

Segments are predicate definitions over traits and event history, recomputed synchronously on each write and again when a time window in a definition lapses. Transitions emit `system.segment_entered` and `system.segment_exited` system events that automations trigger on, except those found by a bulk recompute or an import, which start nobody. See the [Segments guide](/segments/) for predicate semantics. All mutations require organization admin permissions.

## POST /v1/segments

Create a segment

**Auth:** Session token.

**Request body**

```json
{
  "data": {
    "name": "string",
    "appId": "string",
    "description": "string",
    "definition": {
      "match": "all",
      "predicates": [
        {
          "kind": "trait",
          "name": "string",
          "op": "eq",
          "value": {}
        }
      ]
    }
  }
}
```

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `data` | object | yes |  |
| `data.name` | string | yes | length 1–100 |
| `data.appId` | string | yes | length 0–200 |
| `data.description` | string \| null | no |  |
| `data.definition` | object | yes |  |
| `data.definition.match` | "all" \| "any" | no | default `"all"` |
| `data.definition.predicates` | array of variants | yes | items 1–∞ |
| `data.definition.predicates[]` | one of | yes |  |
| `data.definition.predicates[]〈trait〉` | object | yes |  |
| `data.definition.predicates[]〈trait〉.kind` | "trait" | yes |  |
| `data.definition.predicates[]〈trait〉.name` | string | yes | length 1–200 |
| `data.definition.predicates[]〈trait〉.op` | "eq" \| "neq" \| "gt" \| "gte" \| "lt" \| "lte" \| "exists" \| "notExists" \| "contains" \| "before" \| "after" | yes |  |
| `data.definition.predicates[]〈trait〉.value` | any | no |  |
| `data.definition.predicates[]〈event〉` | object | yes |  |
| `data.definition.predicates[]〈event〉.kind` | "event" | yes |  |
| `data.definition.predicates[]〈event〉.name` | string \| string[] | yes |  |
| `data.definition.predicates[]〈event〉.op` | "performed" \| "notPerformed" | yes |  |
| `data.definition.predicates[]〈event〉.atLeast` | integer | no | default `1`; 1 ≤ x ≤ ∞ |
| `data.definition.predicates[]〈event〉.withinDays` | integer | no | 1 ≤ x ≤ ∞ |

**Response 201**

```json
{
  "data": {
    "id": "string",
    "orgId": "string",
    "appId": "string",
    "name": "string",
    "description": "string",
    "tags": [
      "string"
    ],
    "definition": {
      "match": "all",
      "predicates": [
        {
          "kind": "trait",
          "name": "string",
          "op": "eq",
          "value": {}
        }
      ]
    },
    "source": "push",
    "automationKey": "string",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z",
    "memberCount": 42
  },
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true,
    "warnings": [
      {
        "code": "string",
        "message": "string",
        "suggestion": "string"
      }
    ]
  }
}
```

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `data` | object | yes |  |
| `data.id` | string | yes |  |
| `data.orgId` | string | yes |  |
| `data.appId` | string | yes |  |
| `data.name` | string | yes |  |
| `data.description` | string \| null | yes |  |
| `data.tags` | string[] | yes |  |
| `data.definition` | object | yes |  |
| `data.definition.match` | "all" \| "any" | yes | default `"all"` |
| `data.definition.predicates` | array of variants | yes | items 1–∞ |
| `data.definition.predicates[]` | one of | yes |  |
| `data.definition.predicates[]〈trait〉` | object | yes |  |
| `data.definition.predicates[]〈trait〉.kind` | "trait" | yes |  |
| `data.definition.predicates[]〈trait〉.name` | string | yes | length 1–200 |
| `data.definition.predicates[]〈trait〉.op` | "eq" \| "neq" \| "gt" \| "gte" \| "lt" \| "lte" \| "exists" \| "notExists" \| "contains" \| "before" \| "after" | yes |  |
| `data.definition.predicates[]〈trait〉.value` | any | no |  |
| `data.definition.predicates[]〈event〉` | object | yes |  |
| `data.definition.predicates[]〈event〉.kind` | "event" | yes |  |
| `data.definition.predicates[]〈event〉.name` | string \| string[] | yes |  |
| `data.definition.predicates[]〈event〉.op` | "performed" \| "notPerformed" | yes |  |
| `data.definition.predicates[]〈event〉.atLeast` | integer | yes | default `1`; 1 ≤ x ≤ ∞ |
| `data.definition.predicates[]〈event〉.withinDays` | integer | no | 1 ≤ x ≤ ∞ |
| `data.source` | "push" \| "api" | yes |  |
| `data.automationKey` | string \| null | yes |  |
| `data.createdAt` | string (date-time) | yes |  |
| `data.updatedAt` | string (date-time) | yes |  |
| `data.memberCount` | integer | yes | 0 ≤ x ≤ ∞ |
| `meta` | object | no |  |
| `meta.requestId` | string | no |  |
| `meta.nextCursor` | string \| null | no |  |
| `meta.hasMore` | boolean | no |  |
| `meta.warnings` | object[] | no |  |
| `meta.warnings[]` | object | no |  |
| `meta.warnings[].code` | string | yes |  |
| `meta.warnings[].message` | string | yes |  |
| `meta.warnings[].suggestion` | string | no |  |

Errors follow the [shared envelope and code table](/api-conventions/#errors).

## POST /v1/segments/preview

Preview a draft definition

**Auth:** Session token.

**Request body**

```json
{
  "data": {
    "appId": "string",
    "definition": {
      "match": "all",
      "predicates": [
        {
          "kind": "trait",
          "name": "string",
          "op": "eq",
          "value": {}
        }
      ]
    }
  }
}
```

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `data` | object | yes |  |
| `data.appId` | string | yes | length 0–200 |
| `data.definition` | object | yes |  |
| `data.definition.match` | "all" \| "any" | no | default `"all"` |
| `data.definition.predicates` | array of variants | yes | items 1–∞ |
| `data.definition.predicates[]` | one of | yes |  |
| `data.definition.predicates[]〈trait〉` | object | yes |  |
| `data.definition.predicates[]〈trait〉.kind` | "trait" | yes |  |
| `data.definition.predicates[]〈trait〉.name` | string | yes | length 1–200 |
| `data.definition.predicates[]〈trait〉.op` | "eq" \| "neq" \| "gt" \| "gte" \| "lt" \| "lte" \| "exists" \| "notExists" \| "contains" \| "before" \| "after" | yes |  |
| `data.definition.predicates[]〈trait〉.value` | any | no |  |
| `data.definition.predicates[]〈event〉` | object | yes |  |
| `data.definition.predicates[]〈event〉.kind` | "event" | yes |  |
| `data.definition.predicates[]〈event〉.name` | string \| string[] | yes |  |
| `data.definition.predicates[]〈event〉.op` | "performed" \| "notPerformed" | yes |  |
| `data.definition.predicates[]〈event〉.atLeast` | integer | no | default `1`; 1 ≤ x ≤ ∞ |
| `data.definition.predicates[]〈event〉.withinDays` | integer | no | 1 ≤ x ≤ ∞ |

**Response 200**

```json
{
  "data": {
    "memberCount": 42,
    "members": [
      "string"
    ],
    "scanned": 42,
    "truncated": true
  },
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true,
    "warnings": [
      {
        "code": "string",
        "message": "string",
        "suggestion": "string"
      }
    ]
  }
}
```

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `data` | object | yes |  |
| `data.memberCount` | integer | yes | 0 ≤ x ≤ ∞ |
| `data.members` | string[] | yes |  |
| `data.scanned` | integer | yes | 0 ≤ x ≤ ∞ |
| `data.truncated` | boolean | yes |  |
| `meta` | object | no |  |
| `meta.requestId` | string | no |  |
| `meta.nextCursor` | string \| null | no |  |
| `meta.hasMore` | boolean | no |  |
| `meta.warnings` | object[] | no |  |
| `meta.warnings[]` | object | no |  |
| `meta.warnings[].code` | string | yes |  |
| `meta.warnings[].message` | string | yes |  |
| `meta.warnings[].suggestion` | string | no |  |

Errors follow the [shared envelope and code table](/api-conventions/#errors).

## GET /v1/segments

List segments

**Auth:** Session token.

**Query parameters**

```json
{
  "cursor": "string",
  "limit": 50,
  "q": "string",
  "appId": "string"
}
```

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `cursor` | string | no |  |
| `limit` | integer | no | default `50`; 1 ≤ x ≤ 100 |
| `q` | string | no | length 0–200 |
| `appId` | string | no | length 0–200 |

**Response 200**

```json
{
  "data": [
    {
      "id": "string",
      "orgId": "string",
      "appId": "string",
      "name": "string",
      "description": "string",
      "tags": [
        "string"
      ],
      "definition": {
        "match": "all",
        "predicates": [
          {
            "kind": "trait",
            "name": "string",
            "op": "eq",
            "value": {}
          }
        ]
      },
      "source": "push",
      "automationKey": "string",
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true,
    "warnings": [
      {
        "code": "string",
        "message": "string",
        "suggestion": "string"
      }
    ]
  }
}
```

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `data` | object[] | yes |  |
| `data[]` | object | yes |  |
| `data[].id` | string | yes |  |
| `data[].orgId` | string | yes |  |
| `data[].appId` | string | yes |  |
| `data[].name` | string | yes |  |
| `data[].description` | string \| null | yes |  |
| `data[].tags` | string[] | yes |  |
| `data[].definition` | object | yes |  |
| `data[].definition.match` | "all" \| "any" | yes | default `"all"` |
| `data[].definition.predicates` | array of variants | yes | items 1–∞ |
| `data[].definition.predicates[]` | one of | yes |  |
| `data[].definition.predicates[]〈trait〉` | object | yes |  |
| `data[].definition.predicates[]〈trait〉.kind` | "trait" | yes |  |
| `data[].definition.predicates[]〈trait〉.name` | string | yes | length 1–200 |
| `data[].definition.predicates[]〈trait〉.op` | "eq" \| "neq" \| "gt" \| "gte" \| "lt" \| "lte" \| "exists" \| "notExists" \| "contains" \| "before" \| "after" | yes |  |
| `data[].definition.predicates[]〈trait〉.value` | any | no |  |
| `data[].definition.predicates[]〈event〉` | object | yes |  |
| `data[].definition.predicates[]〈event〉.kind` | "event" | yes |  |
| `data[].definition.predicates[]〈event〉.name` | string \| string[] | yes |  |
| `data[].definition.predicates[]〈event〉.op` | "performed" \| "notPerformed" | yes |  |
| `data[].definition.predicates[]〈event〉.atLeast` | integer | yes | default `1`; 1 ≤ x ≤ ∞ |
| `data[].definition.predicates[]〈event〉.withinDays` | integer | no | 1 ≤ x ≤ ∞ |
| `data[].source` | "push" \| "api" | yes |  |
| `data[].automationKey` | string \| null | yes |  |
| `data[].createdAt` | string (date-time) | yes |  |
| `data[].updatedAt` | string (date-time) | yes |  |
| `meta` | object | no |  |
| `meta.requestId` | string | no |  |
| `meta.nextCursor` | string \| null | no |  |
| `meta.hasMore` | boolean | no |  |
| `meta.warnings` | object[] | no |  |
| `meta.warnings[]` | object | no |  |
| `meta.warnings[].code` | string | yes |  |
| `meta.warnings[].message` | string | yes |  |
| `meta.warnings[].suggestion` | string | no |  |

Errors follow the [shared envelope and code table](/api-conventions/#errors).

## GET /v1/segments/{id}

Fetch one segment with its member count

**Auth:** Session token.

**Response 200**

```json
{
  "data": {
    "id": "string",
    "orgId": "string",
    "appId": "string",
    "name": "string",
    "description": "string",
    "tags": [
      "string"
    ],
    "definition": {
      "match": "all",
      "predicates": [
        {
          "kind": "trait",
          "name": "string",
          "op": "eq",
          "value": {}
        }
      ]
    },
    "source": "push",
    "automationKey": "string",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z",
    "memberCount": 42
  },
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true,
    "warnings": [
      {
        "code": "string",
        "message": "string",
        "suggestion": "string"
      }
    ]
  }
}
```

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `data` | object | yes |  |
| `data.id` | string | yes |  |
| `data.orgId` | string | yes |  |
| `data.appId` | string | yes |  |
| `data.name` | string | yes |  |
| `data.description` | string \| null | yes |  |
| `data.tags` | string[] | yes |  |
| `data.definition` | object | yes |  |
| `data.definition.match` | "all" \| "any" | yes | default `"all"` |
| `data.definition.predicates` | array of variants | yes | items 1–∞ |
| `data.definition.predicates[]` | one of | yes |  |
| `data.definition.predicates[]〈trait〉` | object | yes |  |
| `data.definition.predicates[]〈trait〉.kind` | "trait" | yes |  |
| `data.definition.predicates[]〈trait〉.name` | string | yes | length 1–200 |
| `data.definition.predicates[]〈trait〉.op` | "eq" \| "neq" \| "gt" \| "gte" \| "lt" \| "lte" \| "exists" \| "notExists" \| "contains" \| "before" \| "after" | yes |  |
| `data.definition.predicates[]〈trait〉.value` | any | no |  |
| `data.definition.predicates[]〈event〉` | object | yes |  |
| `data.definition.predicates[]〈event〉.kind` | "event" | yes |  |
| `data.definition.predicates[]〈event〉.name` | string \| string[] | yes |  |
| `data.definition.predicates[]〈event〉.op` | "performed" \| "notPerformed" | yes |  |
| `data.definition.predicates[]〈event〉.atLeast` | integer | yes | default `1`; 1 ≤ x ≤ ∞ |
| `data.definition.predicates[]〈event〉.withinDays` | integer | no | 1 ≤ x ≤ ∞ |
| `data.source` | "push" \| "api" | yes |  |
| `data.automationKey` | string \| null | yes |  |
| `data.createdAt` | string (date-time) | yes |  |
| `data.updatedAt` | string (date-time) | yes |  |
| `data.memberCount` | integer | yes | 0 ≤ x ≤ ∞ |
| `meta` | object | no |  |
| `meta.requestId` | string | no |  |
| `meta.nextCursor` | string \| null | no |  |
| `meta.hasMore` | boolean | no |  |
| `meta.warnings` | object[] | no |  |
| `meta.warnings[]` | object | no |  |
| `meta.warnings[].code` | string | yes |  |
| `meta.warnings[].message` | string | yes |  |
| `meta.warnings[].suggestion` | string | no |  |

Errors follow the [shared envelope and code table](/api-conventions/#errors).

## PATCH /v1/segments/{id}

Update a segment

Updating a segment's `definition` recomputes its membership over existing profile history. A segment from your project's `segments/` directory can be updated here too; the next push that would overwrite the change asks first. The segment an automation's trigger defines changes only with that automation.

**Auth:** Session token.

**Request body**

```json
{
  "data": {
    "name": "string",
    "description": "string",
    "definition": {
      "match": "all",
      "predicates": [
        {
          "kind": "trait",
          "name": "string",
          "op": "eq",
          "value": {}
        }
      ]
    }
  }
}
```

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `data` | object | yes |  |
| `data.name` | string | no | length 1–100 |
| `data.description` | string \| null | no |  |
| `data.definition` | object | no |  |
| `data.definition.match` | "all" \| "any" | no | default `"all"` |
| `data.definition.predicates` | array of variants | yes | items 1–∞ |
| `data.definition.predicates[]` | one of | yes |  |
| `data.definition.predicates[]〈trait〉` | object | yes |  |
| `data.definition.predicates[]〈trait〉.kind` | "trait" | yes |  |
| `data.definition.predicates[]〈trait〉.name` | string | yes | length 1–200 |
| `data.definition.predicates[]〈trait〉.op` | "eq" \| "neq" \| "gt" \| "gte" \| "lt" \| "lte" \| "exists" \| "notExists" \| "contains" \| "before" \| "after" | yes |  |
| `data.definition.predicates[]〈trait〉.value` | any | no |  |
| `data.definition.predicates[]〈event〉` | object | yes |  |
| `data.definition.predicates[]〈event〉.kind` | "event" | yes |  |
| `data.definition.predicates[]〈event〉.name` | string \| string[] | yes |  |
| `data.definition.predicates[]〈event〉.op` | "performed" \| "notPerformed" | yes |  |
| `data.definition.predicates[]〈event〉.atLeast` | integer | no | default `1`; 1 ≤ x ≤ ∞ |
| `data.definition.predicates[]〈event〉.withinDays` | integer | no | 1 ≤ x ≤ ∞ |

**Response 200**

```json
{
  "data": {
    "id": "string",
    "orgId": "string",
    "appId": "string",
    "name": "string",
    "description": "string",
    "tags": [
      "string"
    ],
    "definition": {
      "match": "all",
      "predicates": [
        {
          "kind": "trait",
          "name": "string",
          "op": "eq",
          "value": {}
        }
      ]
    },
    "source": "push",
    "automationKey": "string",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z",
    "memberCount": 42
  },
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true,
    "warnings": [
      {
        "code": "string",
        "message": "string",
        "suggestion": "string"
      }
    ]
  }
}
```

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `data` | object | yes |  |
| `data.id` | string | yes |  |
| `data.orgId` | string | yes |  |
| `data.appId` | string | yes |  |
| `data.name` | string | yes |  |
| `data.description` | string \| null | yes |  |
| `data.tags` | string[] | yes |  |
| `data.definition` | object | yes |  |
| `data.definition.match` | "all" \| "any" | yes | default `"all"` |
| `data.definition.predicates` | array of variants | yes | items 1–∞ |
| `data.definition.predicates[]` | one of | yes |  |
| `data.definition.predicates[]〈trait〉` | object | yes |  |
| `data.definition.predicates[]〈trait〉.kind` | "trait" | yes |  |
| `data.definition.predicates[]〈trait〉.name` | string | yes | length 1–200 |
| `data.definition.predicates[]〈trait〉.op` | "eq" \| "neq" \| "gt" \| "gte" \| "lt" \| "lte" \| "exists" \| "notExists" \| "contains" \| "before" \| "after" | yes |  |
| `data.definition.predicates[]〈trait〉.value` | any | no |  |
| `data.definition.predicates[]〈event〉` | object | yes |  |
| `data.definition.predicates[]〈event〉.kind` | "event" | yes |  |
| `data.definition.predicates[]〈event〉.name` | string \| string[] | yes |  |
| `data.definition.predicates[]〈event〉.op` | "performed" \| "notPerformed" | yes |  |
| `data.definition.predicates[]〈event〉.atLeast` | integer | yes | default `1`; 1 ≤ x ≤ ∞ |
| `data.definition.predicates[]〈event〉.withinDays` | integer | no | 1 ≤ x ≤ ∞ |
| `data.source` | "push" \| "api" | yes |  |
| `data.automationKey` | string \| null | yes |  |
| `data.createdAt` | string (date-time) | yes |  |
| `data.updatedAt` | string (date-time) | yes |  |
| `data.memberCount` | integer | yes | 0 ≤ x ≤ ∞ |
| `meta` | object | no |  |
| `meta.requestId` | string | no |  |
| `meta.nextCursor` | string \| null | no |  |
| `meta.hasMore` | boolean | no |  |
| `meta.warnings` | object[] | no |  |
| `meta.warnings[]` | object | no |  |
| `meta.warnings[].code` | string | yes |  |
| `meta.warnings[].message` | string | yes |  |
| `meta.warnings[].suggestion` | string | no |  |

Errors follow the [shared envelope and code table](/api-conventions/#errors).

## DELETE /v1/segments/{id}

Delete a segment

Deleting a segment permanently removes all of its members. A segment from your project's `segments/` directory comes back on the next push that carries its file. The segment an automation's trigger defines goes only with that automation.

**Auth:** Session token.

**Response 200**

```json
{
  "data": {
    "deleted": true
  },
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true,
    "warnings": [
      {
        "code": "string",
        "message": "string",
        "suggestion": "string"
      }
    ]
  }
}
```

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `data` | object | yes |  |
| `data.deleted` | true | yes |  |
| `meta` | object | no |  |
| `meta.requestId` | string | no |  |
| `meta.nextCursor` | string \| null | no |  |
| `meta.hasMore` | boolean | no |  |
| `meta.warnings` | object[] | no |  |
| `meta.warnings[]` | object | no |  |
| `meta.warnings[].code` | string | yes |  |
| `meta.warnings[].message` | string | yes |  |
| `meta.warnings[].suggestion` | string | no |  |

Errors follow the [shared envelope and code table](/api-conventions/#errors).

## GET /v1/segments/{id}/members

List a segment's members

**Auth:** Session token.

**Query parameters**

```json
{
  "cursor": "string",
  "limit": 50
}
```

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `cursor` | string | no |  |
| `limit` | integer | no | default `50`; 1 ≤ x ≤ 100 |

**Response 200**

```json
{
  "data": [
    {
      "segmentId": "string",
      "orgId": "string",
      "profileId": "string",
      "enteredAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true,
    "warnings": [
      {
        "code": "string",
        "message": "string",
        "suggestion": "string"
      }
    ]
  }
}
```

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `data` | object[] | yes |  |
| `data[]` | object | yes |  |
| `data[].segmentId` | string | yes |  |
| `data[].orgId` | string | yes |  |
| `data[].profileId` | string | yes |  |
| `data[].enteredAt` | string (date-time) | yes |  |
| `meta` | object | no |  |
| `meta.requestId` | string | no |  |
| `meta.nextCursor` | string \| null | no |  |
| `meta.hasMore` | boolean | no |  |
| `meta.warnings` | object[] | no |  |
| `meta.warnings[]` | object | no |  |
| `meta.warnings[].code` | string | yes |  |
| `meta.warnings[].message` | string | yes |  |
| `meta.warnings[].suggestion` | string | no |  |

Errors follow the [shared envelope and code table](/api-conventions/#errors).