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

# Buckets

> Frozen, static sets of conversations you can analyze or hand off as a group.

A **bucket** is a static, hand-picked collection of conversations, scoped to a
single [agent](/docs/agents). It holds an explicit membership snapshot: once a
conversation is in a bucket it stays there until you remove it, even if it would
no longer match the filter that first put it there.

That makes buckets the right tool for a fixed body of work — you can pick up a
bucket today and the same set of calls will be waiting tomorrow.

## Creating a bucket

Open **Buckets** and click **New bucket**. Every bucket belongs to one agent —
pick it at creation time. A new bucket starts empty and gets type `static`
(the only type today).

You fill a bucket two ways:

* **Populate from filters** — supply filter criteria (agent, duration, ended
  reason, date range, finding types, and so on) and add every current match in
  one go. The filter snapshot is saved on the bucket, so you can see what
  populated it and re-run the same filter later.
* **Add calls one at a time** — pick individual conversations from the bucket
  detail page or [programmatically](#programmatic-access).

<Note>
  Buckets are agent-scoped, so a filter that matches calls across several agents
  only adds the ones belonging to the bucket's own agent. The rest are reported
  back as `skippedOtherAgentCount` rather than silently dropped.
</Note>

## Membership

Add or remove conversations one at a time from the bucket detail page or
[programmatically](#programmatic-access). Two rules hold everywhere:

* **Same agent.** A conversation can only join a bucket whose agent it belongs
  to. Adding a call from a different agent is rejected.
* **Idempotent re-add.** Adding a conversation that is already in the bucket is a
  no-op — the existing membership row is returned with `alreadyExisted: true`,
  and no duplicate is created.

Removing a conversation that isn't in the bucket returns `{ removed: false }`.

## Editing

From the detail page you can:

* **Rename** the bucket inline.
* **Edit filters** on the **Filters** tab — useful for re-running the saved
  filter to pull in new matches.
* **Delete** the bucket. Deleting a bucket removes the membership snapshot, not
  the underlying conversations.

## Programmatic access

Buckets are first-class in both the [REST API](/api-reference/agents/list-agents) and the
[MCP server](/docs/mcp), using the same org-wide API key.

### REST

| Method & path                                            | Purpose                                                         |
| -------------------------------------------------------- | --------------------------------------------------------------- |
| `GET /v1/buckets`                                        | List buckets (optionally filtered by `agentId`).                |
| `GET /v1/buckets/{id}`                                   | Fetch one bucket.                                               |
| `POST /v1/buckets`                                       | Create a bucket (`agentId`, `name`, optional `type`/`filters`). |
| `GET /v1/buckets/{id}/conversations`                     | List a bucket's conversations.                                  |
| `POST /v1/buckets/{id}/conversations`                    | Add a conversation (`conversationId`).                          |
| `DELETE /v1/buckets/{id}/conversations/{conversationId}` | Remove a conversation.                                          |

Adding a conversation returns `201` when it's newly inserted and `200` when it
was already a member.

### MCP

The same operations are exposed as MCP tools:

* `create_bucket` — create an agent-scoped bucket.
* `add_conversation_to_bucket` / `remove_conversation_from_bucket` — manage
  membership.
* `populate_bucket_from_filters` — add every match for a set of filters.

See the [MCP reference](/docs/mcp) for the full tool schemas.