---
title: Families
api: GET /brands/{brand_id}/families
description: "Get the keyword universe organized by topic families."
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://docs.boringmarketing.com/llms.txt). Append `.md` to any page URL for its markdown version.

Returns all topic families and their keywords discovered during the pipeline run.

## Path parameters

<ParamField path="brand_id" type="string" required>
  The brand UUID.
</ParamField>

## Query parameters

<ParamField query="run_id" type="string">
  Pin results to a specific pipeline run.
</ParamField>

## Response

```json
{
  "brand_id": "brand-uuid",
  "total_families": 12,
  "total_keywords": 847,
  "families": [
    {
      "id": "family-uuid",
      "name": "Marketing Automation",
      "hub_keyword": "marketing automation software",
      "keyword_count": 45,
      "family_type": "demand",
      "brand_ranked_count": 3,
      "brand_avg_position": 28.5,
      "keywords": [
        {
          "keyword": "best marketing automation tools",
          "google_vol": 2400,
          "ai_vol": 89,
          "kd": 42,
          "aio_present": true,
          "content_exists": false,
          "brand_position": null
        }
      ]
    }
  ]
}
```

| Field | Notes |
|---|---|
| `family_type` | One of `demand`, `authority`, or `both`. `demand` families target high-intent commercial keywords; `authority` families target question-form / informational seeds; `both` is mixed. |
| `brand_ranked_count` | How many keywords in this family the brand currently ranks for. |
| `brand_avg_position` | Average rank across the keywords the brand ranks for. `null` when `brand_ranked_count` is 0. |
| `keywords[].keyword` | The only keyword field guaranteed to be present. Other fields (`google_vol`, `ai_vol`, `kd`, `aio_present`, `content_exists`, `brand_position`) are best-effort and may be missing depending on what the data sources returned. |

## Example

```bash
curl -H "X-API-Key: $BM_API_KEY" \
  "https://api.boringmarketing.com/brands/$BRAND_ID/families"
```