Families

GEThttps://api.boringmarketing.com/brands/{brand_id}/families

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

Path parameters

brand_idstringrequired

The brand UUID.

Query parameters

run_idstring

Pin results to a specific pipeline run.

Response

{
  "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

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