Capacities - Cargo Documentation

A capacity is a workload limit you attach to an Allocate node. It counts how many records each member has already received and marks anyone at their limit as unavailable, so territory 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.

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.

Model-based capacity

Instead of counting only Cargo’s own allocations, a capacity can derive existing workload from a data model — 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

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`

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.

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 receives the lead.

Territories

Group members into pools that leads are distributed across.

Build a play

Add an Allocate step that enforces capacity limits.

​Anatomy of a capacity

​Limit types

​Fixed limit

​Expiring windows

​Model-based capacity

​Manage capacities from the CLI

​Apply a capacity during allocation

Territories

Build a play

Anatomy of a capacity

Limit types

Fixed limit

Expiring windows

Model-based capacity

Manage capacities from the CLI

Apply a capacity during allocation