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

# Tags

> One vocabulary for every label on every record

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

|               |                                                                                                                                                    |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Subject**   | `account`, `person` or `path` (an opportunity: a connector and a prospect). Fixed when the group is created, and a tag never moves between groups. |
| **Selection** | `single` holds at most one of the group's tags per record, so adding another replaces it. `multi` holds any number.                                |
| **Closes**    | A flag on a tag, on opportunity groups only. A tag that closes says the conversation on that path is over.                                         |

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.

<Note>
  **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](/account-states).
</Note>

## Reading and writing tags

| You want               | Call                                                                                                                |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| The vocabulary         | [List Tag Groups](/api-reference/list-tag-groups), or [List Tags](/api-reference/list-tags) for a flat lookup by id |
| A new group or tag     | [Create Tag Group](/api-reference/create-tag-group), [Create Tag](/api-reference/create-tag)                        |
| One account's tags     | [Get](/api-reference/get-account-record-tags) / [Set](/api-reference/set-account-record-tags)                       |
| One person's tags      | [Get](/api-reference/get-person-record-tags) / [Set](/api-reference/set-person-record-tags)                         |
| One opportunity's tags | [Get](/api-reference/get-path-record-tags) / [Set](/api-reference/set-path-record-tags)                             |
| A whole selection      | [Bulk Set Record Tags](/api-reference/bulk-set-record-tags), up to 100 records                                      |

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](/api-reference/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.

<Info>
  **`statuses` still works on search and is translated to the matching tags.**
  It is deprecated. New integrations should send `tag` with tag ids.
</Info>

## 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](/hubspot), [Salesforce](/salesforce), [Attio](/attio) — alongside
owner sync and [tier](/tiers) sync.

## Every write is traced

Setting tags logs a `tags_set` entry on the record's [activity
timeline](/record-activity), whether a person, a [Workflow](/workflows), an API
key or an assistant did it.