Skip to main content
A bucket is a static, hand-picked collection of conversations, scoped to a single agent. 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.
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.

​
Membership

Add or remove conversations one at a time from the bucket detail page or programmatically. 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 and the MCP server, using the same org-wide API key.

​
REST

Method & pathPurpose
GET /v1/bucketsList buckets (optionally filtered by agentId).
GET /v1/buckets/{id}Fetch one bucket.
POST /v1/bucketsCreate a bucket (agentId, name, optional type/filters).
GET /v1/buckets/{id}/conversationsList a bucket’s conversations.
POST /v1/buckets/{id}/conversationsAdd 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 for the full tool schemas.