> ## Documentation Index
> Fetch the complete documentation index at: https://developers.chameleon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Segments

> Segments are fundamental to targeting users within Chameleon. They are used for Microsurveys, Tours and Launchers to make sure the right users see the right content at the right moment.


***

With the Chameleon API for Segments, you can:

* Retrieve a list of segments according to the specified parameters.
* Retrieve a single segment based on the `id`.
* List all the Chameleon Experiences (Tours, Microsurveys, Launchers) that are connected to a defined segment.

<a id="schema" />

## Schema

| Property     | Type                  | Description                                                                              |
| ------------ | --------------------- | ---------------------------------------------------------------------------------------- |
| `id`         | ID                    | The Chameleon ID                                                                         |
| `created_at` | timestamp             | When this happened or when this was added to the Database                                |
| `updated_at` | timestamp             | The last time any property was updated                                                   |
| `name`       | string                | The name given by an administrator of Chameleon                                          |
| `items`      | array\<SegmentFilter> | An array of items that each define a [Segmentation Filter expression](/concepts/filters) |
| `items_op`   | enum                  | If each filter item is joined with logical `AND` or `OR`. One of `and` or `or`           |

> For a full list of your User / Company Properties see the [Properties API](/apis/properties)

<a id="segments-index" />

## Listing Segments

Retrieve a list of segments according to the specified parameters.

#### HTTP Request

```http title="GET" theme={null}
https://api.chameleon.io/v3/edit/segments
```

| param    | -        | description                                                                                                                 |
| -------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `limit`  | optional | Defaults to `50` with a maximum of `500`                                                                                    |
| `before` | optional | Used when paginating, use directly from the `cursor` object from the previous response                                      |
| `before` | optional | Read as "created `before`" and can be given as a timestamp to get only `limit` items that were created before this time     |
| `after`  | optional | Read as "created `after`" and can be given as a timestamp or ID to get only `limit` items that were created after this time |

With a timestamp

```json theme={null}
{
  "limit": 100,
  "before": "2029-04-07T12:18:00Z"
}
```

From the previous response `cursor.before`

```json theme={null}
{
  "limit": 500,
  "before": "5f3c4232c712de665632a6d7"
}
```

#### HTTP Response

```json theme={null}
{
  "segments": [
    {
      "id": "5f3c4232c712de665632a6d9",
      "name": "Admins who invited > 3",
      "items": [
        {
          "id": "5f3c4232c712de665632a6d8",
          "kind": "property",
          "prop": "role",
          "op": "eq",
          "value": "admin"
        },
        {
          "id": "5f3c4232c712de665632a6d7",
          "kind": "property",
          "prop": "invited_users_count",
          "op": "gte",
          "value": 3
        }
      ]
    },
    {
      "id": "5f3c4232c712de665632a6e2",
      "name": "Grown Plan Upsell",
       ...
    },
    ...
  ],
  "cursor": {
    "limit": 50,
    "before": "5f3c4232c712de665632a6d7"
  }
}
```

***

<a id="segments-show" />

## Showing a Segment

Retrieve a single Segment.

#### HTTP Request

```http title="GET" theme={null}
https://api.chameleon.io/v3/edit/segments/:id
```

| param | -        | description            |
| ----- | -------- | ---------------------- |
| `id`  | required | A Segment ID to lookup |

#### HTTP Response

```json theme={null}
{
  "segment": {
    "id": "5f3c4232c712de665632a6d7",
    "name": "Admins who invited > 3",
    "items": [
      {
        "id": "5f3c4232c712de665632a6d8",
        "kind": "property",
        "prop": "role",
        "op": "eq",
        "value": "admin"
      },
      {
        "id": "5f3c4232c712de665632a6d9",
        "kind": "property",
        "prop": "invited_users_count",
        "op": "gte",
        "value": 3
      }
    ]
  }
}
```

***

<a id="segment-experiences-index" />

## Listing Related Experiences

A Segment can be configured to be attached to many Chameleon Experiences, including [Microsurveys](/apis/surveys), [Tours](/apis/tours) and [Launchers](/apis/launchers) and [Rate Limit Groups](/apis/limit-groups). This endpoint allows you to list any of these items that are currently attached to the Segment given with the ID

#### HTTP Request

```http title="GET" theme={null}
https://api.chameleon.io/v3/edit/segments/:id/:kind
```

| param  | -        | description                           |
| ------ | -------- | ------------------------------------- |
| `id`   | required | A Segment ID to lookup                |
| `kind` | required | One of `tour`, `survey` or `launcher` |

#### HTTP Response

```json theme={null}
{
  "segment": {
    "id": "5f3c4232c712de665632a6d7",
    "name": "Admins",
    ...
  },
  "tours": [
    {
      "id": "5f3c4232c712de665632a6d5",
      "name": "Revamped Dashboard Launch",
      "style": "auto",
      "position": 4,
      "published_at": "2029-04-07T12:18:00Z",
       ...
    },
  ],
  "cursor": {
    "limit": 50,
    "before": "5f3c4232c712de665632a2a1"
  }
}
```