---
title: "Segment"
description: "<p>Segments are named, logical expressions</p><p>of users.  These segments may logically be built</p><p>using other segments as well.  The segment api</p><p>provides a list of segments built by both the admin, pre-defined</p><p>segments automatically added to each account as well as custom ones</p><p>created through the UI.</p><p>Segments represent a number of concepts:</p><p>* *Segment* A list of users, users are members (or not) of a segment</p><p>* *Trigger* As a user enters, or leaves a segment, this is a trigger.</p><p>   Triggers do not have a Size, only a history of events.</p><p>* *Goal*  A segment that also implies conversion.  In Lytics</p><p>  App, there are *Goals* that show more prominently in a funnel</p><p>  type interface.</p><p>* *Dynamic Attribute* A user belonging to a segment describes an attribute</p><p>   about that user.  For instance *IsPurchaser* is both an attribute</p><p>   that can help personaliation, as well as a segment.  We call these</p><p>   special segments *Aspects* at Lytics.</p><p>* *Metric* A segment when used exclusively for the purposes of</p><p>   tracking conversions/metric.</p><p>The Segment resource has the following attributes:</p><p>| field       | DataType         | Description   |</p><p>|-------------|------------------|---------------|</p><p>| id          | string           | unique id, Lytics assigned</p><p>| created     | Date             | Created date</p><p>| updated     | Date             | Last Updated Date</p><p>| kind        | string           | What Type of segment from list above [\"aspect\",\"goal\"] or leave empty for \"segment\".</p><p>| slug        | string           | customer-assigned unique id (We auto assigned by slugifying <span data-type=\"inlineCode\" class=\"code\">Name</span> if not provided).</p><p>| name        | string           | Name of this segment</p><p>| description | string           | Long text description (optional)</p><p>| is_public   | bool             | Is this segment available as part of user profile api (entity api)</p><p>| segment_ql  | string           | Segment QL Logical Expression</p><p>| tags        | []string         | List of tags, for organization purposes</p><p>To see a list of available fields available for segmentation rules see **catalog** api.</p>"
url: "https://www.contentstack.com/docs/developers/apis/lytics-api/v1/segment"
product: "Contentstack"
doc_type: "guide"
audience:
  - developers
  - admins
version: "current"
last_updated: "2026-11-05"
---

# Segment

Segments are named, logical expressions

of users. These segments may logically be built

using other segments as well. The segment api

provides a list of segments built by both the admin, pre-defined

segments automatically added to each account as well as custom ones

created through the UI.

Segments represent a number of concepts:

\* \*Segment\* A list of users, users are members (or not) of a segment

\* \*Trigger\* As a user enters, or leaves a segment, this is a trigger.

Triggers do not have a Size, only a history of events.

\* \*Goal\* A segment that also implies conversion. In Lytics

App, there are \*Goals\* that show more prominently in a funnel

type interface.

\* \*Dynamic Attribute\* A user belonging to a segment describes an attribute

about that user. For instance \*IsPurchaser\* is both an attribute

that can help personaliation, as well as a segment. We call these

special segments \*Aspects\* at Lytics.

\* \*Metric\* A segment when used exclusively for the purposes of

tracking conversions/metric.

The Segment resource has the following attributes:

| field | DataType | Description |

|-------------|------------------|---------------|

| id | string | unique id, Lytics assigned

| created | Date | Created date

| updated | Date | Last Updated Date

| kind | string | What Type of segment from list above \["aspect","goal"\] or leave empty for "segment".

| slug | string | customer-assigned unique id (We auto assigned by slugifying Name if not provided).

| name | string | Name of this segment

| description | string | Long text description (optional)

| is\_public | bool | Is this segment available as part of user profile api (entity api)

| segment\_ql | string | Segment QL Logical Expression

| tags | \[\]string | List of tags, for organization purposes

To see a list of available fields available for segmentation rules see \*\*catalog\*\* api.

## SegmentList

### SegmentList

**GET** `/api/segment`

Get list of \*\*Segments\*\* . Segments can refer to any Table.

The two main tables you will be working with are \*User\* and \*Content\*.

\`\`

\# Grab all segments from "user" table

curl "$LIOAPI/api/segment" -s -H "Authorization: $LIOKEY" | jq '.'

\# Grab all "Content Collections" (ney, segments)

curl "$LIOAPI/api/segment?table=content" -s -H "Authorization: $LIOKEY" | jq '.'

\`\`

#### Query Parameters

- **account_id** (optional)
  Your Lytics account ID.
- **table** (optional)
  Table for segments to fetch, "user" by default, specify "content" for content collections (aka segments).
- **valid** (optional)
  True, False or "all". Get all segments, only valid, or only invalid.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "data": [
    {
      "id": "7a7f76ff97ad0e3e96c162f74aee8f8f",
      "account_id": "4f7b525bdba058fc096757a6",
      "author_id": "user_12345",
      "kind": "segment",
      "segment_ql": "FILTER AND ( visits > 5, last_visit >= \"2015-04-01 00:00:00Z\", last_visit <  \"2015-04-02 00:00:00Z\")",
      "created": "2014-08-04T21:18:20.124Z",
      "updated": "2014-08-04T21:18:20.124Z",
      "description": "Casual users have been active in the last 90 days and show no extreme behavioral patterns.",
      "is_public": true,
      "name": "Recent Visits",
      "slug_name": "recent_visits",
      "tags": [
        "email_trigger"
      ]
    }
  ]
}
```

## Segment Create

### Segment Create

**POST** `/api/segment`

Create A segment. See \*\*/api/segment/validate\*\*

method for testing out Segmentation rules.

Pass a \*\*Segment QL\*\* logic expression to create

a Segment.

\`\`

\# Plain Text api will extract the "our\_test\_activelist" as the "slug" and "name" of

\# the segment

curl -s -XPOST "https://api.lytics.io/api/segment" \\

\-H "Content-type: text/plain" \\

\-H "Authorization: $LIOKEY" \\

\-d'

FILTER AND (

visits > 5,

last\_visit >= "now-30d",

scores.momentum > 10

)

ALIAS our\_test\_activelist

' | jq '.'

\# or try managing segments in files so you can check them in

\# to Bitbucket or Github. Also addresses field-

curl -s -XPOST 'https://api.lytics.io/api/segment' \\

\-H 'Content-type: text/plain' \\

\-H "Authorization: your\_api\_token" \\

\-d @my\_segment.json | jq '.'

\# Json Api Allows a few more fields such as description

curl -s -XPOST "https://api.lytics.io/api/segment" \\

\-H "Authorization: $LIOKEY" \\

\-H "Content-type: application/json" \\

\-d'

{

"name":"Most Active Users",

"segment\_ql": "FILTER AND (visits > 5,last\_visit >= \\"now-30d\\", scores.momentum > 10)",

"slug\_name":"our\_test\_activelist",

"is\_public": true,

"description":"a description of what this is for",

"tags":\["email\_personalization","product"\]

}

' | jq '.'

\# create a json file of a segment

curl -s -XPOST "$LIOAPI/api/segment" \\

\-H "Authorization: $LIOKEY" \\

\-H "Content-type: application/json" \\

\-d @segment.json | jq '.'

\# Content Collection (ney, "Segment")

curl -s -XPOST "https://api.lytics.io/api/segment" \\

\-H "Content-type: text/plain" \\

\-H "Authorization: $LIOKEY" \\

\-d'

FILTER AND (

EXISTS imageurls -- Make sure they have images

aspects = "article" -- Ensure they are of type article

PATH = "blog" -- only show those from the /blog part of site

created > "now-30d" -- only those authored in last 30 days

)

FROM content

WITH

name = "Recent Blog Articles With Images"

ALIAS recent\_blog\_articles

' | jq '.'

\`

SegmentQL

\=============================

The query language for segments

\`

Filter = "FILTER" Phrase \[FROM\] \[ALIAS\]

Phrase = AND | OR | Expression

AND = "AND" (Phrase, Phrase, ...)

OR = "OR" (Phrase, Phrase, ...)

Expression = NOT

| Comparison

| EXISTS

| IN

| CONTAINS

| LIKE

| IncludeSegment

NOT = "NOT" Phrase

Comparison = Identifier ComparisonOp Literal

ComparisonOp = ">" | ">=" | "<" | "<=" | "==" | "!="

EXISTS = "EXISTS" Identifier

IN = Identifier "IN" (Literal, Literal, ...)

CONTAINS = Identifier "CONTAINS" Literal

LIKE = Identifier "LIKE" String # uses \* for wildcards

IncludeSegment = "INCLUDE" Identifier

\# Optional From, not needed for segmentation on users

FROM = "FROM" Identifier

\# Alias for giving a segment a "name" which is how

\# it will be included from other filters

ALIAS = "ALIAS" Identifier

Literal = String | Int | Float | Bool | Timestamp

\# note, identifiers may not contain spaces, or periods, etc

Identifier = \[a-zA-Z\]\[a-zA-Z0-9\_\]+

\`

\*\*Examples\*\*

\`

\# Simple single expression filter

FILTER "abc" IN some\_identifier

FILTER NOT foo

\# Filters have an optional "Alias" used for

\# referencing

FILTER AND ( channelsct > 1 AND scores.quantity > 20 ) ALIAS multi\_channel\_active

\# Filters can references to other Filters

FILTER AND (

EXISTS email,

NOT INCLUDE multi\_channel\_active

)

FILTER AND (

visits > 5,

NOT INCLUDE someotherfilter,

)

\# negation

FILTER NOT AND ( ... )

\# Compound filter

FILTER AND (

visits > 5,

last\_visit >= "2015-04-01 00:00:00Z",

last\_visit < "2015-04-02 00:00:00Z",

)

\# Like

FILTER url LIKE "/blog/"

\# date math

\# Operator is either + or -. Units supported are y (year), M (month),

\# w (week), d (date), h (hour), m (minute), and s (second)

FILTER last\_visit > "now-24h"

\# IN

city IN ("Portland, OR", "Seattle, WA", "Newark, NJ")

\# Complex

AND (

OR (

foo == true

bar != 5

)

EXISTS signup\_date

OR (

NOT bar IN (1, 2, 4, 5)

INCLUDE SomeOtherFilter

)

)

\# Time Windows

\# Can only be used on timebucket fields

\# Answers the question "at least X in Y days", where X can be one of (1, 5, 10, 25, 50, 100)

\# and Y can be one of (7, 30) days.

#

\# timewindow(fieldname, X, Y)

FILTER timewindow(bucketfield, 5, 7)

\# Between

FILTER AND (

\_modified BETWEEN "2015-07-01" AND "2016-08-01"

)

\`\`

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "data": {
    "id": "7a7f76ff97ad0e3e96c162f74aee8f8f",
    "account_id": "4f7b525bdba058fc096757a6",
    "author_id": "4f7b525bdba058fc096757a6",
    "kind": "segment",
    "segment_ql": "FILTER AND ( visits > 5, last_visit >= \"2015-04-01 00:00:00Z\", last_visit <  \"2015-04-02 00:00:00Z\")",
    "created": "2014-08-04T21:18:20.124Z",
    "updated": "2014-08-04T21:18:20.124Z",
    "description": "Casual users have been active in the last 90 days and show no extreme behavioral patterns.",
    "name": "Recent Visits",
    "slug_name": "recent_visits",
    "tags": [
      "email_trigger"
    ]
  }
}
```

## Segment Fetch

### Segment Fetch

**GET** `/api/segment/{id}`

Fetch a segment by \*\*id\*\* or \*\*slug\*\*

#### URL Parameters

- **id** (required)
  id, or slug of a segment, part of url path

#### Query Parameters

- **account_id** (optional)
  Your Lytics account ID.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "data": {
    "id": "7a7f76ff97ad0e3e96c162f74aee8f8f",
    "account_id": "4f7b525bdba058fc096757a6",
    "author_id": "4f7b525bdba058fc096757a6",
    "kind": "segment",
    "segment_ql": "FILTER AND ( visits > 5, last_visit >= \"2015-04-01 00:00:00Z\", last_visit <  \"2015-04-02 00:00:00Z\")",
    "created": "2014-08-04T21:18:20.124Z",
    "updated": "2014-08-04T21:18:20.124Z",
    "description": "Casual users have been active in the last 90 days and show no extreme behavioral patterns.",
    "name": "Recent Visits",
    "slug_name": "recent_visits",
    "tags": [
      "email_trigger"
    ]
  }
}
```

## Segment Update

### Segment Update

**PUT** `/api/segment/{id}`

Update A segment.

\`\`

\# You can upsert (insert if new, update if exists)

\# by POSTing to api and the ALIAS will be used to lookup

\# the existing one and update it.

curl -s -XPOST "https://api.lytics.io/api/segment" \\

\-H "Content-type: text/plain" \\

\-H "Authorization: $LIOKEY" \\

\-d'

FILTER AND (

visits > 5,

last\_visit >= "now-30d",

scores.momentum > 10

)

ALIAS our\_test\_activelist

' | jq '.'

\# Json Api Allows a few more fields such as description

curl -s -XPUT "https://api.lytics.io/api/segment/123456id" \\

\-H "Authorization: $LIOKEY" \\

\-H "Content-type: application/json" \\

\-d'

{

"name":"Most Active Users",

"segment\_ql": "FILTER AND (visits > 5,last\_visit >= \\"now-30d\\", scores.momentum > 10)",

"slug\_name":"our\_test\_activelist",

"is\_public": true,

"description":"a description of what this is for"

}

' | jq '.'

\`\`

#### URL Parameters

- **id** (required)
  id, or slug of a segment, part of url path

#### Query Parameters

- **account_id** (optional)
  Your Lytics account ID.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "data": {
    "id": "7a7f76ff97ad0e3e96c162f74aee8f8f",
    "account_id": "4f7b525bdba058fc096757a6",
    "author_id": "4f7b525bdba058fc096757a6",
    "kind": "segment",
    "segment_ql": "FILTER AND ( visits > 5, last_visit >= \"2015-04-01 00:00:00Z\", last_visit <  \"2015-04-02 00:00:00Z\")",
    "created": "2014-08-04T21:18:20.124Z",
    "updated": "2014-08-04T21:18:20.124Z",
    "description": "Casual users have been active in the last 90 days and show no extreme behavioral patterns.",
    "name": "Recent Visits",
    "slug_name": "recent_visits",
    "tags": [
      "email_trigger"
    ]
  }
}
```

## Segment Delete

### Segment Delete

**DELETE** `/api/segment/{id}`

Delete A segment.

#### URL Parameters

- **id** (required)
  id, or slug of a segment, part of url path

#### Query Parameters

- **account_id** (optional)
  Your Lytics account ID.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
No Content
```

## SegmentSize

### SegmentSize

**POST** `/api/segment/size`

Get size of a single Segment using SegmentQL, not saved.

This api is very rate throttled, 1/10 seconds.

\`\`

\# Post a SegmentQL query to size api to fetch size

curl -s -XPOST "https://api.lytics.io/api/segment/size" \\

\-H "Content-type: text/plain" \\

\-H "Authorization: your\_api\_token" \\

\-d'

FILTER AND (

visits > 5,

last\_visit >= "now-30d",

scores.momentum > 10

)

' | jq '.'

\`\`

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "data": {
    "id": "",
    "name": "active",
    "slug_name": "active",
    "size": 10402
  }
}
```

## SegmentValidate

### SegmentValidate

**POST** `/api/segment/validate`

Validate single Segment Query Statement

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "status": 200,
  "message": "success",
  "data": null
}
```

## SegmentSizes

### SegmentSizes

**GET** `/api/segment/sizes`

Get bunch of segment sizes.

#### Query Parameters

- **account_id** (optional)
  Your Lytics account ID.
- **ids** (required)
  list of ids to get, format = ids\[\]=123&ids\[\]=234 OR ids=123,345 etc, see standard \[\]string param doc

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "data": [
    {
      "id": "456dert",
      "name": "Active",
      "slug_name": "active",
      "size": 10402
    },
    {
      "id": "1234abcd",
      "type": "custom",
      "slug_name": "active",
      "size": 45236
    }
  ]
}
```

## SegmentScan

### SegmentScan

**GET** `/api/segment/{segId}/scan`

Get a paged list of \*\*Users\*\* for a \*\*Segment\*\*.

#### URL Parameters

- **segId** (required)
  segment Id in path

#### Query Parameters

- **account_id** (optional)
  Your Lytics account ID.
- **id** (optional)
  segment Id in querystring instead of path then use api/segment/scan
- **limit** (optional)
  num of rows to return per call, default = 10, max = 100
- **splits** (optional)
  1,2,3 comma seperated list of ints 0-99 for a-b split testing (a=1,5,8 )
- **start** (optional)
  optional ID of a previous segment scan to resume, must be recent this is retrieved from the next parameter in JSON response
- **meta** (optional)
  optional boolean, whether to include schema in response
- **sortfield** (optional)
  field to sort on
- **sortorder** (optional)
  \[desc,asc\]
- **recent** (optional)
  short cut for last visit timestamp desc \[t,true,\]
- **segments** (optional)
  JSON of ad-hoc segment, or pass this in http Body
- **fields** (optional)
  list of fields to include in response

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
null
```

## Segment Batch Delete

### Segment Batch Delete

**DELETE** `/api/segment/{segId}/scan`

Delete a Batch of segments

\`\`

\# ids=1234 convert this to \[\]string{"123"}

\# ids=\[123,456\] convert this to \[\]string{"123","456"}

\# ids=123,456 convert this to \[\]string{"123","456"}

\# ids=123&ids=456 convert this to \[\]string{"123","456"}

\# ids\[\]=123&ids\[\]=456 convert this to \[\]string{"123","456"} Note that we alias ids\[\] = ids

curl -s -XDELETE -H "Content-Type: application/json" \\

\- H "Authorization: $LIOKEY" \\

"https://api.lytics.io/api/segment?ids=21decdea54052ea1285478ecac53d1ed,59e39389fbf738d75246749a6146d280" \\

| jq '.'

\`\`

#### URL Parameters

- **segId** (required)
  segment Id in path

#### Query Parameters

- **account_id** (optional)
  Your Lytics account ID.
- **id** (optional)
  segment Id in querystring instead of path then use api/segment/scan
- **limit** (optional)
  num of rows to return per call, default = 10, max = 100
- **splits** (optional)
  1,2,3 comma seperated list of ints 0-99 for a-b split testing (a=1,5,8 )
- **start** (optional)
  optional ID of a previous segment scan to resume, must be recent this is retrieved from the next parameter in JSON response
- **meta** (optional)
  optional boolean, whether to include schema in response
- **sortfield** (optional)
  field to sort on
- **sortorder** (optional)
  \[desc,asc\]
- **recent** (optional)
  short cut for last visit timestamp desc \[t,true,\]
- **segments** (optional)
  JSON of ad-hoc segment, or pass this in http Body
- **fields** (optional)
  list of fields to include in response

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
No Content
```

## SegmentAttribution

### SegmentAttribution

**GET** `/api/segment/{segId}/attribution`

Get single attribution

#### URL Parameters

- **segId** (required)
  segment id

#### Query Parameters

- **account_id** (optional)
  Your Lytics account ID.
- **limit** (optional)
- **refresh** (optional)

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "data": [
    {
      "id": "1234",
      "metrics": [
        {
          "ts": "1413149713466",
          "value": 1002
        },
        {
          "ts": "1413149713455",
          "value": 1005
        }
      ]
    },
    {
      "id": "1111",
      "metrics": [
        {
          "ts": "1413149713466",
          "value": 1002
        },
        {
          "ts": "1413149713455",
          "value": 1005
        }
      ]
    }
  ]
}
```

## SegmentAttributionList

### SegmentAttributionList

**GET** `/api/segment/attribution`

Get bunch of segment sizes

#### Query Parameters

- **account_id** (optional)
  Your Lytics account ID.
- **refresh** (optional)
  SYSADMIN ONLY, refresh cache

\+ Default false
- **limit** (optional)
  number of historical data points to fetch

\+ Default 168
- **ids** (required)
  list of ids to get, format = ids\[\]=123&ids\[\]=234 OR ids=123,345 etc, see standard \[\]string param doc

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "data": [
    {
      "id": "1234",
      "metrics": [
        {
          "ts": "1413149713466",
          "value": 1002
        },
        {
          "ts": "1413149713455",
          "value": 1005
        }
      ]
    },
    {
      "id": "1111",
      "metrics": [
        {
          "ts": "1413149713466",
          "value": 1002
        },
        {
          "ts": "1413149713455",
          "value": 1005
        }
      ]
    }
  ]
}
```

## SegmentFieldInfo

### SegmentFieldInfo

**GET** `/api/segment/{segId}/fieldinfo`

Get field info by segment

#### URL Parameters

- **segId** (required)
  the segment id

#### Query Parameters

- **account_id** (optional)
  Your Lytics account ID.
- **limit** (optional)
- **fields** (optional)
  optional list, or comma separated list of string fields to include

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
null
```