> ## 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.

# Bulk Set Record Tags

> The same tags across up to 100 records

One call for a selection, whatever the table: accounts, people or opportunities.
Every subject in one request must be the same `subject_type`, and the tags must
come from a group for that subject.

The response reports how many records were written. It does not echo each
record's resulting tags: a selection of 100 rows would be a response bigger than
the page it repaints.

## Body

<ParamField body="subjects" type="object[]" required>
  1 to 100 records. Each carries `subject_type` and the key its type uses:

  | `subject_type` | Key                                             |
  | -------------- | ----------------------------------------------- |
  | `account`      | `company_id`                                    |
  | `person`       | `linkedin_id`                                   |
  | `path`         | `client_linkedin_id` and `prospect_linkedin_id` |
</ParamField>

<ParamField body="tag_ids" type="string[]" required>
  Tag ids, from [List Tag Groups](/api-reference/list-tag-groups).
</ParamField>

<ParamField body="mode" type="string" default="replace">
  `add`, `remove` or `replace`.
</ParamField>

<ParamField body="group_id" type="string">
  Narrows a `replace` to one group.
</ParamField>

<Warning>
  **Prefer `add` over `replace` across a mixed selection.** A bulk `replace`
  discards whatever each record already carried, and those rows rarely carried
  the same thing. The app's bulk action sends `add` for exactly this reason.
</Warning>

<Note>
  **101 records is an error, not a truncation.** The cap is the table's own page
  size doubled, which keeps one transaction short enough not to hold row locks
  across a slow client. Split the selection and send two calls.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://api.clustr-ai.com/api/public/record-tags/bulk" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "subjects": [
        { "subject_type": "account", "company_id": "9c4d5e6f-1a2b-4c3d-8e9f-0a1b2c3d4e5f" },
        { "subject_type": "account", "company_id": "7a1b2c3d-4e5f-4061-8a2b-3c4d5e6f7081" }
      ],
      "tag_ids": ["7f3e1a22-0c5d-4c1e-9f8a-2b4d6e8f0a12"],
      "mode": "add"
    }'
  ```

  ```bash cURL (opportunities) theme={null}
  curl -X PUT "https://api.clustr-ai.com/api/public/record-tags/bulk" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "subjects": [
        {
          "subject_type": "path",
          "client_linkedin_id": "nicdelaye",
          "prospect_linkedin_id": "jane-smith"
        }
      ],
      "tag_ids": ["8f652e61-edfa-4a8c-8763-cc4902dd386b"],
      "mode": "add"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": { "updated": 2 }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": { "message": "too many records in one request", "code": "BAD_REQUEST" }
  }
  ```
</ResponseExample>