# Campaigns

> Create, update, and delete campaigns. Manage campaign membership (items).

Campaigns are **mixed-platform**: a single campaign can contain creators and videos across TikTok and Instagram. Campaign items reference creators, videos, or sub-campaigns regardless of platform. To view a campaign's performance split by platform, query the [aggregate endpoints](https://www.trackagoat.com/docs/api-reference/aggregate.md) (e.g. `video-leaderboard`, `creator-leaderboard`) with the `platform` filter, or read a video's `platform` field directly.

## GET /api/v2/campaigns

List campaigns in your organization.

### Request

```bash
curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v2/campaigns?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 |

### Response fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | uuid | Campaign ID |
| `project_id` | uuid | Project this campaign belongs to |
| `name` | string | Campaign name |
| `readme` | string \| null | Markdown notes / agent context (rendered in the Notes tab) |
| `metadata` | object | Agent-writable structured data |
| `created_at` | ISO 8601 | Creation timestamp |
| `updated_at` | ISO 8601 | Last update |

---

## POST /api/v2/projects/{projectId}/campaigns

Create a campaign. Requires the `write` scope.

```bash
curl -X POST \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "Summer Drop Campaign"}' \
  "https://www.trackagoat.com/api/v2/projects/<projectId>/campaigns"
```

---

## PATCH /api/v2/campaigns/{id}

Update a campaign. At least one field required. Requires the `write` scope.

### Body

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Campaign name (max 200 chars). |
| `readme` | string \| null | Markdown notes. Replaces the whole README; pass `null` to clear. |
| `expected_readme_version` | string | Optional, only with `readme`: the `readme_version` from your last read (`GET /api/v2/notes/campaign/{id}` or a previous `PATCH` response). If the README changed since, nothing is written and the response is **409** `notes_conflict` with `meta.current_readme_version`. Without it, `readme` overwrites whatever is there. |
| `target_views` | number \| null | Target total view goal for the campaign. |
| `target_at` | ISO 8601 datetime \| null | Target completion date. |

The response is the updated campaign plus its `readme_version`. To add to the README without replacing it, use [`POST /api/v2/notes/campaign/{id}`](https://www.trackagoat.com/docs/api-reference/notes.md) with `mode: "append"`.

---

## DELETE /api/v2/campaigns/{id}

Delete a campaign and all its item memberships. Requires the `write` scope.

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

---

## POST /api/v2/campaigns/{id}/items

Add a creator, video, or sub-campaign to a campaign. Requires the `write` scope.

```bash
curl -X POST \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -d '{"item_type": "creator", "item_id": "<uuid>"}' \
  https://www.trackagoat.com/api/v2/campaigns/<campaignId>/items
```

| Body field | Type | Description |
|-----------|------|-------------|
| `item_type` | `creator` \| `video` \| `campaign` | The type of item to add. |
| `item_id` | uuid | ID of the creator, video, or sub-campaign. It must be in the same project as the campaign, and a creator must be active. |

Returns **404** if the item doesn't exist in the campaign's project, and **409** if the item is already in the campaign or would create a circular reference.

---

## DELETE /api/v2/campaigns/{id}/items

Remove an item from a campaign. Pass the `item_type` and `item_id` in the request body. Requires the `write` scope.

```bash
curl -X DELETE \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -d '{"item_type": "creator", "item_id": "<uuid>"}' \
  https://www.trackagoat.com/api/v2/campaigns/<campaignId>/items
```

Returns `{ "deleted": true }`, or `{ "deleted": false }` when the item wasn't in the campaign.

---

## Analytics (time-series)

Campaign time-series analytics have moved to the unified endpoint. The new endpoint also supports breakdown by video or creator, multi-granularity buckets, and prior-period comparison.

```bash
# Daily new views for a campaign
curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v2/analytics?entity=campaign&entity_id=<uuid>&metric=views&mode=new&granularity=day"

# Monthly cumulative views
curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v2/analytics?entity=campaign&entity_id=<uuid>&metric=views&mode=cumulative&granularity=month"

# Top-10 video breakdown
curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v2/analytics?entity=campaign&entity_id=<uuid>&metric=views&breakdown=video&top_n=10"

# Engagement rate (derived)
curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v2/analytics?entity=campaign&entity_id=<uuid>&metric=engagement_rate_by_views&mode=rate"

# Multi-entity overlay: compare up to 5 campaigns side-by-side
curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v2/analytics?entity=campaign&entity_ids=<uuid1>,<uuid2>,<uuid3>&metric=views&granularity=week"
```

See the [Analytics API reference](https://www.trackagoat.com/docs/api-reference/analytics.md) for the full parameter and response documentation.

> **Removed:** `GET /api/v2/campaigns/{id}/stats` returns `410 Gone`. Use `GET /api/v2/analytics?entity=campaign&entity_id={id}` instead. For a per-platform split of a campaign, use the [aggregate](https://www.trackagoat.com/docs/api-reference/aggregate.md) `video-leaderboard` or `creator-leaderboard` endpoints with the `platform` query parameter.

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