# Content groups

> Link the same logical content across platforms and read its combined, cross-platform stats.

A **content group** links the same logical piece of content across platforms (for example, the same video posted to both TikTok and Instagram) so its combined performance can be viewed together. A video can belong to **at most one** content group.

## Content group fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | uuid | Content group ID |
| `project_id` | uuid | Project this group belongs to |
| `org_id` | uuid | Owning organization ID |
| `title` | string | Group title |
| `notes` | string \| null | Freeform notes |
| `created_by` | uuid \| null | User who created the group |
| `video_ids` | array of uuid | Videos that are members of the group |
| `created_at` | ISO 8601 | When the group was created |
| `updated_at` | ISO 8601 | Last update |

---

## GET /api/v2/content-groups

List content groups in your organization.

```bash
curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v2/content-groups?project_id=<uuid>"
```

### Query parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `project_id` | uuid | None | Filter to a specific project |
| `limit` | number | 50 | Items per page (max 100) |
| `cursor` | string | None | Pagination cursor |

Returns a paginated array of [content group objects](#content-group-fields).

---

## POST /api/v2/content-groups

Create a content group. Requires the `write` scope. Optionally seed it with member videos.

```bash
curl -X POST \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "project_id": "<uuid>",
    "title": "Launch teaser",
    "notes": "Same clip on TikTok + Reels",
    "video_ids": ["<videoUuid1>", "<videoUuid2>"]
  }' \
  "https://www.trackagoat.com/api/v2/content-groups"
```

### Body

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `project_id` | uuid | required | Project to create the group in. |
| `title` | string | required | Group title (1 to 200 chars). |
| `notes` | string \| null | None | Freeform notes. |
| `video_ids` | array of uuid | `[]` | Videos to add (up to 200). Must belong to the same project. |

> **Note:**
>
> A video can live in only one group. Any `video_ids` that already belong to another group are skipped; the returned `video_ids` reflect which videos were actually attached.

Returns 201 with the created group, or 404 if the project isn't found.

---

## GET /api/v2/content-groups/{id}

Get a single content group.

```bash
curl -H "Authorization: Bearer tga_<key>" \
  https://www.trackagoat.com/api/v2/content-groups/<uuid>
```

Returns a [content group object](#content-group-fields). 404 if not found.

---

## PATCH /api/v2/content-groups/{id}

Rename, edit notes, or add/remove member videos. At least one field is required. Requires the `write` scope.

```bash
curl -X PATCH \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Launch teaser (final)",
    "add_video_ids": ["<videoUuid3>"],
    "remove_video_ids": ["<videoUuid1>"]
  }' \
  https://www.trackagoat.com/api/v2/content-groups/<uuid>
```

### Body

| Field | Type | Description |
|-------|------|-------------|
| `title` | string | Rename the group (1 to 200 chars). |
| `notes` | string \| null | Edit notes. Pass `null` to clear. |
| `add_video_ids` | array of uuid | Videos to add to the group (up to 200). |
| `remove_video_ids` | array of uuid | Videos to remove from the group (up to 200). |

Returns the updated [content group object](#content-group-fields). 404 if not found.

---

## DELETE /api/v2/content-groups/{id}

Delete a content group. The member videos themselves are not deleted; they are simply unlinked. Requires the `write` scope.

```bash
curl -X DELETE \
  -H "Authorization: Bearer tga_<key>" \
  https://www.trackagoat.com/api/v2/content-groups/<uuid>
```

Returns `{ "deleted": true }`.

---

## GET /api/v2/content-groups/{id}/stats

Get combined stats for a content group: current metrics summed across every member video, plus a per-platform breakdown.

```bash
curl -H "Authorization: Bearer tga_<key>" \
  https://www.trackagoat.com/api/v2/content-groups/<uuid>/stats
```

### Response

```json
{
  "data": {
    "video_count": 3,
    "totals": {
      "view_count": 1250000,
      "like_count": 84000,
      "comment_count": 3100,
      "share_count": 900
    },
    "by_platform": {
      "tiktok": { "video_count": 2, "view_count": 1000000, "like_count": 70000, "comment_count": 2500, "share_count": 800 },
      "instagram": { "video_count": 1, "view_count": 250000, "like_count": 14000, "comment_count": 600, "share_count": 100 }
    }
  },
  "error": null,
  "meta": null
}
```

### Response fields

| Field | Type | Description |
|-------|------|-------------|
| `video_count` | number | Number of videos in the group |
| `totals` | object | Summed `view_count`, `like_count`, `comment_count`, `share_count` across the group |
| `by_platform` | object | Keyed by platform; each value carries `video_count` plus the same four metric totals for that platform |

A group with no member videos returns `video_count: 0`, zeroed `totals`, and an empty `by_platform`.

- [Videos](https://www.trackagoat.com/docs/api-reference/videos.md): List videos and filter by content group.
- [Creators and accounts guide](https://www.trackagoat.com/docs/guides/accounts.md): How the multi-platform model works.

---
Source: https://www.trackagoat.com/docs/api-reference/content-groups