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 (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#
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//campaigns#
Create a campaign. Requires the write scope.
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/#
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} with mode: "append".
DELETE/api/v2/campaigns/#
Delete a campaign and all its item memberships. Requires the write scope.
curl -X DELETE -H "Authorization: Bearer tga_<key>" \
https://www.trackagoat.com/api/v2/campaigns/<uuid>POST/api/v2/campaigns//items#
Add a creator, video, or sub-campaign to a campaign. Requires the write scope.
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//items#
Remove an item from a campaign. Pass the item_type and item_id in the request body. Requires the write scope.
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>/itemsReturns { "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.
# 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 for the full parameter and response documentation.
Removed:
GET /api/v2/campaigns/{id}/statsreturns410 Gone. UseGET /api/v2/analytics?entity=campaign&entity_id={id}instead. For a per-platform split of a campaign, use the aggregatevideo-leaderboardorcreator-leaderboardendpoints with theplatformquery parameter.