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

# Capacities

> Cap how many records each member receives within a time window — with fixed limits, expiring windows, or limits derived from a data model.

A **capacity** is a workload limit you attach to an [Allocate](/workflows/overview) node. It counts how many records each [member](/reference/revenue-organization) has already received and marks anyone at their limit as unavailable, so [territory](/reference/revenue-organization/territories) round-robin skips them and leads flow to reps with headroom.

## Anatomy of a capacity

| Field                                      | Description                                                                       |
| ------------------------------------------ | --------------------------------------------------------------------------------- |
| `name`                                     | Human-readable name (e.g. `AE Capacity`).                                         |
| `color`                                    | Visual tag: `orange`, `red`, `purple`, `green`, `yellow`, or `grey`.              |
| `description`                              | Optional free-text note.                                                          |
| `memberCapacity`                           | Max distinct records a member can hold in the current window. `null` = unlimited. |
| `allocationExpirationPolicy`               | How the counting window resets (see below). `null` = allocations never expire.    |
| `modelUuid`                                | Optional data model to derive existing allocations from (model-based capacity).   |
| `filter`, `idColumnSlug`, `timeColumnSlug` | Required when `modelUuid` is set — how to read records from that model.           |

## Limit types

### Fixed limit

Set `memberCapacity` to the number of records each member may hold. Once a member reaches it, they're skipped until an allocation expires (or forever, if there's no expiration policy). Leave it `null` for no limit.

### Expiring windows

`allocationExpirationPolicy` controls when past allocations stop counting, so a member's capacity refills over time. The interval can be:

`hourly`, `daily`, `weekly`, `monthly`, `quarterly`, `yearly`, or `null` (never expires).

Each interval works in one of two ways:

* **Sliding** — a rolling window (e.g. the last 24 hours for `daily`). This is the default.
* **Fixed boundary** — the window resets at a set point (e.g. every day at `09:00` UTC, or every Monday). Fixed boundaries take extra fields such as `time` (UTC `HH:MM`), `weekDay` (`1`=Monday … `7`=Sunday), `day`, `month`, or `minute` depending on the interval.

<Note>
  A member's used capacity is the count of **distinct record IDs** allocated to
  them within the current window — re-allocating the same record doesn't double-count.
</Note>

### Model-based capacity

Instead of counting only Cargo's own allocations, a capacity can derive existing workload from a [data model](/models/overview) — for example, counting each rep's open opportunities. Set `modelUuid` and provide:

| Field            | Purpose                                                                                                  |
| ---------------- | -------------------------------------------------------------------------------------------------------- |
| `filter`         | Segmentation filter selecting the relevant rows (e.g. open deals), including which member owns each row. |
| `idColumnSlug`   | Column used as the record ID.                                                                            |
| `timeColumnSlug` | Date column used as the allocation timestamp (for expiration windows).                                   |

Cargo syncs those rows into allocation counts, matching each row's owner to a member. A sync runs automatically when the linked model emits new data (and can also be triggered via the API); the capacity records when it last synced. At allocation time, both the synced historical counts and any new allocations made since the last sync are added together to decide availability.

## Manage capacities from the CLI

```bash theme={null}
cargo-ai revenue-organization capacity list
cargo-ai revenue-organization capacity get <uuid>

# Simple, expiring capacity
cargo-ai revenue-organization capacity create \
  --name "AE Capacity" --color purple \
  --member-capacity 50 \
  --allocation-expiration-policy daily

# Model-based capacity
cargo-ai revenue-organization capacity create \
  --name "Open deals cap" --color green \
  --member-capacity 20 \
  --model-uuid "<model-uuid>" \
  --id-column-slug "record_id" \
  --time-column-slug "created_at" \
  --filter '{ ... }'

cargo-ai revenue-organization capacity update \
  --uuid "<uuid>" --member-capacity 75

cargo-ai revenue-organization capacity remove <uuid>
```

| Command  | Required            | Optional                                                                                                                                                          |
| -------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create` | `--name`, `--color` | `--description`, `--member-capacity`, `--allocation-expiration-policy`, `--model-uuid`, `--id-column-slug`, `--time-column-slug`, `--filter`                      |
| `update` | `--uuid`            | `--name`, `--color`, `--description`, `--member-capacity`, `--allocation-expiration-policy`, `--model-uuid`, `--id-column-slug`, `--time-column-slug`, `--filter` |

<Note>
  Segmentation `--filter` JSON uses the `conjonction` key (Cargo's intentional
  spelling). When `--model-uuid` is set, `--filter`, `--id-column-slug`, and
  `--time-column-slug` are required.
</Note>

## Apply a capacity during allocation

A capacity does nothing on its own — attach its `capacityUuid` to an **Allocate** node. Whichever allocation mode you use (`territory`, `members`, `email`, or `matching`), members at their limit are marked unavailable and skipped; if everyone is full, the [fallback member](/reference/revenue-organization/territories) receives the lead.

<CardGroup cols={2}>
  <Card title="Territories" icon="map" href="/reference/revenue-organization/territories">
    Group members into pools that leads are distributed across.
  </Card>

  <Card title="Build a play" icon="play" href="/plays/overview">
    Add an Allocate step that enforces capacity limits.
  </Card>
</CardGroup>