# Lists

Lists are sets of values used to parameterize [rules](/en/rules/) without having to edit them on every change. In [expressions](/en/rules/expression-syntax/#collections-), a list is referenced by its name with the `@` prefix:

```
$user_id in @quarantined_customers
```

Keeping data in lists separates operational responsibility (maintaining the items) from technical responsibility (maintaining the rules), reducing the risk of accidental changes to rules. Each list holds text values of up to 128 characters, with no line breaks.

## Create a list

Under **Settings > Lists > New list**:

1. Choose a name using only letters, numbers, hyphens, and underscores (e.g., `quarantined-customers`).
2. Add an optional description.
3. Click **Create list**.

The name is the identifier used in expressions and **cannot be changed after creation**: a rule referencing the old name would stop finding the items.

## Add items

Open the list and click **Add items**:

1. Enter one item per line.
2. Add an optional description, repeated across every item in the insertion (useful for referencing a support ticket, for example).
3. Optionally, set an expiration, in minutes, hours, or days, at least 5 minutes and at most 2 years. Without an expiration, the item stays until removed manually.

Each list holds up to **10,000 items**. You can add up to **1,000 items per insertion**; to register larger volumes, split the content across more than one insertion.

Items can also be added through the API, with `POST /lists/{list_id}/items`. The expiration is provided in `expires_in`, as an ISO 8601 period (`PT30M`, `PT12H`, `P1D`).

## Items added by rules

A rule can write to a list while processing an event, with the [add to list](/en/rules/actions/add_to_list/) action. This way, a rule incorporates what it has already observed: a condition detects the behavior and records the value in the list, and later events check that list with an ordinary condition.

When following a list written by rules, keep in mind that:

- items appear **with no description and no author**, since they were not registered by a person;
- a value detected again **renews the expiration** of the existing item, instead of creating another one;
- when the list is **full**, new values stop being added; it is worth tracking the item count in automatically fed lists.

## Query and remove items

Items can be paginated or searched through the search box at the top of the table. To remove one, use **⋮ > Remove** on the item, or **Remove all items** to clear the list.

Items with an expiration are removed automatically by periodic sweeps, which run every few minutes. That is why an item may still count in a condition for a few minutes past its expiration, and also why the minimum expiration is 5 minutes.

## Remove a list

A list can only be removed when it is empty and is not used by any active rule or monitor. Remove the items and the references before deleting it.