# Ranges reference

> Range properties, stage changes, and the errors that clients raise.

This page lists the properties of a [range](https://docs.synnaxlabs.com/reference/ranges), how each stage change sets its times, and the errors that clients raise.

## Properties

* [`key`](https://docs.synnaxlabs.com/reference/ranges/reference#key)`UUID`

  The unique ID of the range. Synnax makes one when you leave it out. A create fails when a range already has the key.

* [`name`](https://docs.synnaxlabs.com/reference/ranges/reference#name)`string`\* Required

  The name of the range, at least one character. Names do not have to be unique.

* [`time_range`](https://docs.synnaxlabs.com/reference/ranges/reference#time-range)`TimeRange`\* Required

  The interval of the range. It includes the start and excludes the end. The start cannot be after the end, and neither can be zero.

* [`color`](https://docs.synnaxlabs.com/reference/ranges/reference#color)`string`

  A hex color such as `"#FF0000"`. The client returns it as a color object. Python and TypeScript can change or clear it later. Line plots show only ranges that have a color. The Console cannot set it. An [Arc automation](https://docs.synnaxlabs.com/reference/ranges/arc) can.

* [`parent`](https://docs.synnaxlabs.com/reference/ranges/reference#parent)`Range | UUID`

  The parent range. Python takes the range or its key. TypeScript takes the key. Set it when you create the range, or change or clear it later from Python or TypeScript.

* [`labels`](https://docs.synnaxlabs.com/reference/ranges/reference#labels)`UUID[]`

  The keys of the [labels](https://docs.synnaxlabs.com/reference/ranges/metadata#labels) of the range. Set them when you create the range, or add and remove them later.

* [`retrieve_if_name_exists`](https://docs.synnaxlabs.com/reference/ranges/reference#retrieve_if_name_exists)`boolean`

  Python only. Returns an existing range with the same name instead of creating a new one. See [create ranges](https://docs.synnaxlabs.com/reference/ranges/create).

Metadata is not a property of the create call. See [metadata and labels](https://docs.synnaxlabs.com/reference/ranges/metadata).

## Stages

The Console computes the stage of a range from its times and the current time:

| Stage       | When                                                    |
| ----------- | ------------------------------------------------------- |
| To do       | The range has no start, or it starts in the future.     |
| In progress | The range has started and has not ended, or has no end. |
| Completed   | The range has ended.                                    |

Each stage change in the Console sets a time:

| From        | Select            | Change                                                               |
| ----------- | ----------------- | -------------------------------------------------------------------- |
| To do       | **Start**         | The start becomes now. The end stays.                                |
| To do       | **Stop**          | The end becomes now. A start in the future also becomes now.         |
| In progress | **Stop**          | The end becomes now.                                                 |
| In progress | **Move to to do** | The start moves to the end. A range with no end loses its start too. |
| Completed   | **Reopen**        | The end is removed. The start stays.                                 |

In the range explorer, the **Start** and **Stop** menu items make the same changes.

On the timeline, **Unschedule** clears the start and the end, and **Remove end** clears the end. When you move the start past the end, the end moves with it and the range keeps its length. The same is true when you move the end before the start.

## Errors

| Error                | When                                                                                                                                                                                                         |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `NotFoundError`      | A retrieve matches no range.                                                                                                                                                                                 |
| `MultipleFoundError` | A retrieve by name, or with `one`, matches more than one range.                                                                                                                                              |
| Validation error     | A create has a key that a range already has, an empty name, a zero start or end, a start after its end, a parent or label that does not exist, or a parent that is the range itself or a range nested in it. |
