---
title: "Segments"
description: "<p>Create and manage audience segments.</p>"
url: "https://www.contentstack.com/docs/developers/apis/lytics-api/segments"
product: "Contentstack"
doc_type: "guide"
audience:
  - developers
  - admins
version: "current"
last_updated: "2026-11-05"
---

# Segments

Create and manage audience segments.

## Get segments

### Get segments

**GET** `/v2/segment`

Get a list of segments for an account

#### Query Parameters

- **account_id** (optional)
  The account ID. Defaults to the user's default account.
- **table** (optional)
  Filter by table
- **valid** (optional)
  Filter by valid (true|false|all)
- **kind** (optional)
  Filter by kind (segment|goal|aspect|conversion|managed|all)

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "_meta": {},
  "data": [
    {
      "account_id": "string",
      "aid": 0,
      "ast": {
        "args": [
          {}
        ],
        "ident": "string",
        "op": "string",
        "val": "string"
      },
      "author_id": "string",
      "category": "string",
      "created": "string",
      "datemath_calc": true,
      "deleted": true,
      "description": "string",
      "field_changes_fields": [
        "string"
      ],
      "fields": [
        "string"
      ],
      "forward_datemath": true,
      "groups": [
        "string"
      ],
      "id": "string",
      "identities": [
        "string"
      ],
      "includes": [
        "string"
      ],
      "invalid": true,
      "invalid_reason": "string",
      "is_public": true,
      "kind": "string",
      "name": "string",
      "public_name": "string",
      "ql_resolved": "string",
      "save_hist": true,
      "schedule_exit": true,
      "segment_ql": "string",
      "size": 0,
      "slug_name": "string",
      "table": "string",
      "tags": [
        "string"
      ],
      "updated": "string",
      "withs_ql": "string"
    }
  ],
  "request_id": "string",
  "status": 0
}
```

## Create segment

### Create segment

**POST** `/v2/segment`

Create a segment

#### Query Parameters

- **account_id** (optional)
  The account ID. Defaults to the user's default account.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "_meta": {},
  "data": {
    "account_id": "string",
    "aid": 0,
    "ast": {
      "args": [
        {}
      ],
      "ident": "string",
      "op": "string",
      "val": "string"
    },
    "author_id": "string",
    "category": "string",
    "created": "string",
    "datemath_calc": true,
    "deleted": true,
    "description": "string",
    "field_changes_fields": [
      "string"
    ],
    "fields": [
      "string"
    ],
    "forward_datemath": true,
    "groups": [
      "string"
    ],
    "id": "string",
    "identities": [
      "string"
    ],
    "includes": [
      "string"
    ],
    "invalid": true,
    "invalid_reason": "string",
    "is_public": true,
    "kind": "string",
    "name": "string",
    "public_name": "string",
    "ql_resolved": "string",
    "save_hist": true,
    "schedule_exit": true,
    "segment_ql": "string",
    "size": 0,
    "slug_name": "string",
    "table": "string",
    "tags": [
      "string"
    ],
    "updated": "string",
    "withs_ql": "string"
  },
  "request_id": "string",
  "status": 0
}
```

## Delete segments

### Delete segments

**DELETE** `/v2/segment`

Delete multiple segments

#### Query Parameters

- **account_id** (optional)
  The account ID. Defaults to the user's default account.
- **ids** (required)
  The segment IDs

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "_meta": {},
  "data": {
    "deleted": [
      "string"
    ],
    "not_deleted": [
      "string"
    ],
    "segments": [
      {
        "deleted": true,
        "id": "string",
        "reason": "string",
        "segments": {
          "property1": [
            "string"
          ],
          "property2": [
            "string"
          ]
        }
      }
    ]
  },
  "request_id": "string",
  "status": 0
}
```

## Add/Remove segment in/from the exclusion list

### Add/Remove segment in/from the exclusion list

**POST** `/v2/segment/exclude/{operation}`

Adds/Removes the passed segment id in/from the exclusion list. Exclusion list allows to exclude all the users from the segment during the export job. Pass auth\_id to scope the exclusion to one authorization; workflow-level and auth-level exclusions are combined, never substituted.

#### URL Parameters

- **operation** (required)
  Operation add or remove

#### Query Parameters

- **account_id** (optional)
  The account ID. Defaults to the user's default account.
- **workflow** (optional)
  Workflow slug.
- **segment_id** (optional)
  Segment id. The segment that needs to be added/removed in/from the exclusion list.
- **auth_id** (optional)
  Authorization id. Scopes the exclusion to jobs delivering through this authorization. Omit workflow to apply it to every workflow using the authorization.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "_meta": {},
  "data": {},
  "request_id": "string",
  "status": 0
}
```

## Get segment

### Get segment

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

Get a segment by ID or slug

#### URL Parameters

- **id** (required)
  The segment ID or segment slug

#### Query Parameters

- **account_id** (optional)
  The account ID. Defaults to the user's default account.
- **sizes** (optional)
  Include size

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "_meta": {},
  "data": {
    "account_id": "string",
    "aid": 0,
    "ast": {
      "args": [
        {}
      ],
      "ident": "string",
      "op": "string",
      "val": "string"
    },
    "author_id": "string",
    "category": "string",
    "created": "string",
    "datemath_calc": true,
    "deleted": true,
    "description": "string",
    "field_changes_fields": [
      "string"
    ],
    "fields": [
      "string"
    ],
    "forward_datemath": true,
    "groups": [
      "string"
    ],
    "id": "string",
    "identities": [
      "string"
    ],
    "includes": [
      "string"
    ],
    "invalid": true,
    "invalid_reason": "string",
    "is_public": true,
    "kind": "string",
    "name": "string",
    "public_name": "string",
    "ql_resolved": "string",
    "save_hist": true,
    "schedule_exit": true,
    "segment_ql": "string",
    "size": 0,
    "slug_name": "string",
    "table": "string",
    "tags": [
      "string"
    ],
    "updated": "string",
    "withs_ql": "string"
  },
  "request_id": "string",
  "status": 0
}
```

## Update segment

### Update segment

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

Update a segment

#### URL Parameters

- **id** (required)
  The segment ID

#### Query Parameters

- **account_id** (optional)
  The account ID. Defaults to the user's default account.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "_meta": {},
  "data": {
    "account_id": "string",
    "aid": 0,
    "ast": {
      "args": [
        {}
      ],
      "ident": "string",
      "op": "string",
      "val": "string"
    },
    "author_id": "string",
    "category": "string",
    "created": "string",
    "datemath_calc": true,
    "deleted": true,
    "description": "string",
    "field_changes_fields": [
      "string"
    ],
    "fields": [
      "string"
    ],
    "forward_datemath": true,
    "groups": [
      "string"
    ],
    "id": "string",
    "identities": [
      "string"
    ],
    "includes": [
      "string"
    ],
    "invalid": true,
    "invalid_reason": "string",
    "is_public": true,
    "kind": "string",
    "name": "string",
    "public_name": "string",
    "ql_resolved": "string",
    "save_hist": true,
    "schedule_exit": true,
    "segment_ql": "string",
    "size": 0,
    "slug_name": "string",
    "table": "string",
    "tags": [
      "string"
    ],
    "updated": "string",
    "withs_ql": "string"
  },
  "request_id": "string",
  "status": 0
}
```

## Delete segment

### Delete segment

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

Delete a segment

#### URL Parameters

- **id** (required)
  The segment ID

#### Query Parameters

- **account_id** (optional)
  The account ID. Defaults to the user's default account.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "_meta": {},
  "data": {},
  "request_id": "string",
  "status": 0
}
```