# contactTagUsage

Free-form tags, least-used first: contactCount (visible, unarchived), orgContactCount (org, +archived; null w/o view-all: 0 proves nothing), dependents. maxContactCount 0 = unused (view-all). filterTree: MATCHING contacts per tag, carried tags first, no org count/dependents. Never countContacts per tag; getDeletionImpact before deleting.

- Call: `POST https://server.goliathdata.com/api/v1/call` with `{ "operationId": "contactTagUsage", "variables": {...} }`
- Scope: `READ`
- Type: query
- Idempotency: a read; rejects `Idempotency-Key`
- Rate-limited: no
- Result cap: `limit` is clamped to 100, without an error

## Variables

- `limit`: `Int` (default `50`)
- `offset`: `Int` (default `0`)
- `maxContactCount`: `Int`
- `filterTree`: `JSON`

## Response (data, an example)

```json
{
  "contactQuery": {
    "contactTagUsage": {
      "tags": [
        {
          "id": "<ID>",
          "name": "…",
          "isEditable": true,
          "contactCount": 0,
          "orgContactCount": 0,
          "dependents": [
            {
              "groupKind": "FILTER",
              "count": 0
            }
          ]
        }
      ],
      "totalCount": 0,
      "hasMore": true
    }
  }
}
```

## Example

```bash
curl https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer $GOLIATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operationId": "contactTagUsage",
    "variables": {}
  }'
```