Skip to main content
A tag is any label your workspace puts on a record. Accounts, people and opportunities each carry their own, and they all come from the same place: a tag group. A group is a named set of tags for one kind of record. “Segment” on accounts, “Relationship” on people, “Status” on warm intros. You name the groups, you name the tags, and nothing in Clustr invents either.

​
Groups decide three things

A record type holds at most 20 groups, and a group at most 50 tags.

​
A status is a tag

There is no separate status any more. What used to be an opportunity status is an ordinary tag in a path group, usually still named Status, with the same id it always had. The group is single, so setting one of its tags replaces the previous one, exactly as a status did. A terminal status is a tag with closes: true. Which means the old vocabulary still reads: an id you stored as a status id is a tag id, and it still works where a tag id is asked for.
Closed does not mean hidden. A record carrying a closing tag sorts last and draws with a neutral pill; it stays visible and filterable. The one control that removes a row from a table is dismiss — see Account States.

​
Reading and writing tags

Every write takes a mode: add keeps what is already there, remove takes tags off, and replace leaves exactly what you send. Send group_id with a replace to confine it to one group.

​
Filtering on tags

Search Opportunities takes tag, a list of tag ids, and the rule is the one the tables use:
  • Tags from the same group are OR. tag=contacted&tag=meeting-booked finds intros carrying either.
  • Tags from different groups are AND. Adding a tag from a second group narrows the result to records carrying something from both.
That is what makes groups worth having: each group is a question, and the tags in it are the answers you accept. In the app, the Accounts table adds one more: no tag in this group, which is what the seeded “New” view is built on. That filter is app-side only; the API key surface filters tags on opportunity search.
statuses still works on search and is translated to the matching tags. It is deprecated. New integrations should send tag with tag ids.

​
Tags and your CRM

A tag group can be mapped to a CRM property, per provider, so a group’s tags and the property’s options stay in step. The direction is the same vocabulary the owner and tier mappings use: Clustr sets the value, your CRM sets the value, or paused. It is edited in Settings ▸ Tags in the app, not over the API. The related mappings are documented on each provider’s page — HubSpot, Salesforce, Attio — alongside owner sync and tier sync.

​
Every write is traced

Setting tags logs a tags_set entry on the record’s activity timeline, whether a person, a Workflow, an API key or an assistant did it.