List Tag Groups

GET

tag-groups

curl "https://api.clustr-ai.com/api/public/tag-groups?subject_type=path" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

groups = requests.get(
    "https://api.clustr-ai.com/api/public/tag-groups",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"subject_type": "path"},
).json()["data"]["groups"]

status = next(g for g in groups if g["name"] == "Status")
by_name = {t["name"]: t["id"] for t in status["tags"]}

await fetch("https://api.clustr-ai.com/api/public/tag-groups?subject_type=account", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});

{
  "success": true,
  "data": {
    "groups": [
      {
        "id": "2b7c9d10-4e5f-4a61-9c22-8d3f1a7b0e44",
        "subject_type": "path",
        "name": "Status",
        "selection": "single",
        "position": 0,
        "is_system": false,
        "tags": [
          {
            "id": "8f652e61-edfa-4a8c-8763-cc4902dd386b",
            "group_id": "2b7c9d10-4e5f-4a61-9c22-8d3f1a7b0e44",
            "name": "Contacted",
            "color": "#3B82F6",
            "position": 0,
            "closes": false
          },
          {
            "id": "7e4cc70e-2644-4b1e-9006-57222533dde4",
            "group_id": "2b7c9d10-4e5f-4a61-9c22-8d3f1a7b0e44",
            "name": "Not interested",
            "color": "#EF4444",
            "position": 1,
            "closes": true
          }
        ]
      }
    ]
  }
}

{
  "success": false,
  "error": { "message": "subject_type must be account, person or path", "code": "BAD_REQUEST" }
}

A tag group is a named set of tags for one kind of record. Every label on a record is a tag in one of these groups, so this is the lookup that makes every other tag call usable: assignments and filters are by id, and the ids come from here. See Tags for the model.

The three subjects

`subject_type`	Labels	Addressed by
`account`	Companies	the company UUID (`company_id`)
`person`	People, connectors included	the person’s LinkedIn id
`path`	Opportunities, a connector and a prospect	the pair of LinkedIn ids

A status is a tag. What used to be an opportunity status is a tag in a path group, usually still named Status. That group is single, so setting one of its tags replaces the previous one. A tag with closes: true is what used to be a terminal status: the conversation on that path is over.

Query Parameters

string

account, person or path. Omit for all three.

string

Set to true to add how many records carry each tag, as tags_with_counts[].subject_count. Off by default, because the count is an aggregate across three assignment tables and a picker does not show it. It is what tells you whether a tag is safe to delete.

Response Fields

array

The groups, in display order.

string

The group’s id. Pass it as group_id when creating a tag, or as group_id on a tag write to scope a replace to this group.

string

account, person or path. Fixed when the group is created.

string

single holds at most one of the group’s tags per record, so adding another replaces it. multi holds any number.

boolean

true for a group Clustr seeds and depends on. It can be renamed, but DELETE on it returns 422.

array

The group’s tags, in display order: id, name, color, position and closes.

curl "https://api.clustr-ai.com/api/public/tag-groups?subject_type=path" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

groups = requests.get(
    "https://api.clustr-ai.com/api/public/tag-groups",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"subject_type": "path"},
).json()["data"]["groups"]

status = next(g for g in groups if g["name"] == "Status")
by_name = {t["name"]: t["id"] for t in status["tags"]}

await fetch("https://api.clustr-ai.com/api/public/tag-groups?subject_type=account", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});

{
  "success": true,
  "data": {
    "groups": [
      {
        "id": "2b7c9d10-4e5f-4a61-9c22-8d3f1a7b0e44",
        "subject_type": "path",
        "name": "Status",
        "selection": "single",
        "position": 0,
        "is_system": false,
        "tags": [
          {
            "id": "8f652e61-edfa-4a8c-8763-cc4902dd386b",
            "group_id": "2b7c9d10-4e5f-4a61-9c22-8d3f1a7b0e44",
            "name": "Contacted",
            "color": "#3B82F6",
            "position": 0,
            "closes": false
          },
          {
            "id": "7e4cc70e-2644-4b1e-9006-57222533dde4",
            "group_id": "2b7c9d10-4e5f-4a61-9c22-8d3f1a7b0e44",
            "name": "Not interested",
            "color": "#EF4444",
            "position": 1,
            "closes": true
          }
        ]
      }
    ]
  }
}

{
  "success": false,
  "error": { "message": "subject_type must be account, person or path", "code": "BAD_REQUEST" }
}

curl "https://api.clustr-ai.com/api/public/tag-groups?subject_type=path" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

groups = requests.get(
    "https://api.clustr-ai.com/api/public/tag-groups",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"subject_type": "path"},
).json()["data"]["groups"]

status = next(g for g in groups if g["name"] == "Status")
by_name = {t["name"]: t["id"] for t in status["tags"]}

await fetch("https://api.clustr-ai.com/api/public/tag-groups?subject_type=account", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});

{
  "success": true,
  "data": {
    "groups": [
      {
        "id": "2b7c9d10-4e5f-4a61-9c22-8d3f1a7b0e44",
        "subject_type": "path",
        "name": "Status",
        "selection": "single",
        "position": 0,
        "is_system": false,
        "tags": [
          {
            "id": "8f652e61-edfa-4a8c-8763-cc4902dd386b",
            "group_id": "2b7c9d10-4e5f-4a61-9c22-8d3f1a7b0e44",
            "name": "Contacted",
            "color": "#3B82F6",
            "position": 0,
            "closes": false
          },
          {
            "id": "7e4cc70e-2644-4b1e-9006-57222533dde4",
            "group_id": "2b7c9d10-4e5f-4a61-9c22-8d3f1a7b0e44",
            "name": "Not interested",
            "color": "#EF4444",
            "position": 1,
            "closes": true
          }
        ]
      }
    ]
  }
}

{
  "success": false,
  "error": { "message": "subject_type must be account, person or path", "code": "BAD_REQUEST" }
}

API Reference

Import

Search

Jobs

Network

Opportunities

Owners

Accounts

Account States

Saved Views

Workflows

Intro Requests

Record Activity

Lists

Tags

Account Tags

Target Accounts

Client Companies

ICP

Competitor Monitoring

Connector Refresh

Notifications

List Tag Groups

The three subjects

Query Parameters

Response Fields

​The three subjects

​Query Parameters

​Response Fields

The three subjects

Query Parameters

Response Fields