> ## 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.
# Tours
> A Tour is a sequence of steps that shows to your end-users when they meet all of the predefined matching criteria, including:
* **First step URL (on the right page) - required**
* **Segmentation matches (User is the right person) - required but can be to match All Users**
* **Element appears on the page - optional**
* **Element must be clicked on or hovered over - optional**
* **etc.**
*To know more about Tours, you can visit our [product documentation](https://help.chameleon.io/en/articles/3521469-understanding-tours).*
***
With the Chameleon API for Tours, you can:
* List all the existing Tours according to the indicated parameters.
* Retrieve a single Tour.
## 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 |
| `style` | string | The delivery method of this Tour: One of `auto` or `manual` |
| `position` | number | The order that these appear in lists (starting from 0) |
| `experiment_at` | timestamp | When [Experimentation](https://help.chameleon.io/en/articles/1069709-a-b-testing-chameleon-tours) was turned on. |
| `experiment_range` | string | The range of `Profile#percent` that will be included in the experiment |
| `segment_ids` | array\ | The Chameleon IDs of the configured [Segments](/apis/segments#schema) |
| `published_at` | timestamp | The time this was most recently published |
| `tag_ids` | array\ | The Chameleon IDs of the [Tags](/apis/tags) attached to this model |
| `rate_unlimit_at` | timestamp | This item is excluded from [Rate limiting](https://help.chameleon.io/en/articles/3513345-rate-limiting-experiences) |
| `dashboard_url` | string | Direct link to this Tour in the Chameleon Dashboard |
| `content_summary` | string | A brief summary of the Tour content |
| `content_semantics` | string | Semantic analysis of the Tour content |
| `audience_summary` | string | A brief summary of the target audience |
| `stats` | object | Aggregated statistics for this model (all-time) |
| `stats.started_count` | number | Number of your end-users who saw this |
| `stats.last_started_at` | timestamp | Most recent time any user saw this |
| `stats.completed_count` | number | Number of your end-users who completed/finished this |
| `stats.last_completed_at` | timestamp | Most recent time any user completed/finished this |
| `stats.exited_count` | number | Number of your end-users who dismissed/exited this |
| `stats.last_exited_at` | timestamp | Most recent time any user dismissed/exited this |
## List Tours
List all the Tours that follow the specified parameters.
#### HTTP Request
```http title="GET" theme={null}
https://api.chameleon.io/v3/edit/tours
```
| 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 |
#### HTTP Response
```json theme={null}
{
"tours": [
{
"id": "5f3c4232c712de665632a6d5",
"name": "Revamped Dashboard Launch",
"style": "auto",
"position": 4,
"published_at": "2029-04-07T12:18:00Z",
...
},
{
"id": "5f3c4232c712de665632a2a1",
"name": "Growth plan upsell banner 2029-02",
"style": "auto",
"position": 3,
"published_at": "2029-04-07T12:18:00Z",
...
},
...
],
"cursor": {
"limit": 50,
"before": "5f3c4232c712de665632a2a1"
}
}
```
## Update a Tour
Update a single Tour to change the [Environments](/apis/urls) or to Publish it.
#### HTTP Request
```http title="PATCH" theme={null}
https://api.chameleon.io/v3/edit/tours/:id
```
| param | - | description |
| -------------- | -------- | -------------------------------------------------------------------------------------------- |
| `id` | required | A Tour ID to update |
| `url_group_id` | optional | An [Environment](/apis/urls) ID prefixed with `+` to add or or `-` to remove the Environment |
| `tag_id` | optional | A [Tag](/apis/tags) ID prefixed with `+` to add or or `-` to remove the Tag |
| `published_at` | optional | The published time of this Tour (set to now to trigger a publish) |
To **Publish** the Tour send the current timestamp in `iso8601` format
```json theme={null}
{
"published_at": "2029-04-07T12:18:00Z"
}
```
To **Unpublish** the Tour set the `published_at` to `null`
```json theme={null}
{
"published_at": null
}
```
To **add** the `5e3c4232c712de666d55632a` Environment use a `+` prefix
```json theme={null}
{
"url_group_id": "+5e3c4232c712de666d55632a"
}
```
To **remove** the `5e3c4232c712de666d55632a` Environment use a `-` prefix
```json theme={null}
{
"url_group_id": "-5e3c4232c712de666d55632a"
}
```
## Filtering by Segment
See [Listing Related models](/apis/segments#segment-experiences-index)
## Retrieve a Tour
Retrieve a single Tour.
#### HTTP Request
```http title="GET" theme={null}
https://api.chameleon.io/v3/edit/tours/:id
```
| param | - | description |
| ----- | -------- | ------------------- |
| `id` | required | A Tour ID to lookup |
```json theme={null}
{
"tour": {
"id": "5f3c4232c712de665632a2a1",
"name": "Growth plan upsell banner 2029-02",
"style": "auto",
"position": 3,
"published_at": "2029-04-07T12:18:00Z",
...
}
}
```