Data model

Hierarchy

Trackagoat is multi-platform. A creator is a person or brand; each creator owns one or more accounts, where an account is a single presence on a platform (TikTok, Instagram, or YouTube). Videos hang off accounts. Tracking configuration (mode, start/end dates, follower stats, last_scraped_at) lives on the account, not the creator. A creator can have several accounts, even more than one on the same platform.

Organization
  └── Project(s)
        ├── Creator(s)              : a person/brand (1..n accounts)
        │     └── Account(s)        : one platform presence, tiktok | instagram | youtube
        │           └── Video(s)    : videos/posts from that account
        ├── Video(s)                : standalone videos added by URL (carry platform + account_id)
        ├── Content Group(s)        : link the same content across platforms
        └── Campaign(s)             : named groupings (can nest)
              ├── → Creator(s)
              ├── → Video(s)
              └── → Campaign(s) (recursive)

Data is scoped to the organization of the API key. A single API call fetches data across all projects unless you filter by project_id. Most list endpoints (/api/v2/creators, /api/v2/accounts, /api/v2/videos, the analytics aggregates) accept a platform filter.

The current API is /api/v2; the previous v1 API has been retired.

Entity reference

Project

Creator

A creator embeds its accounts[]. Creator-level counts are the aggregate across all its accounts; the top-level handle is the primary account's handle (the TikTok account if present, otherwise the earliest-added).

Creator-level writes (PATCH /api/v2/creators/{id}) accept only display_name, readme, and is_active. The handle and tracking configuration live on the account: change them via PATCH /api/v2/accounts/{id}.

Account

One platform presence owned by a creator. Tracking config and the raw follower/engagement snapshot live here.

Fetch accounts via GET /api/v2/accounts (filter by creator_id, project_id, or platform), GET /api/v2/creators/{id}/accounts, or embedded in a creator. Per-account follower/stat history: GET /api/v2/accounts/{id}/stats.

Video

Content Group

Links the same logical content across platforms (e.g. the same clip posted as a TikTok, a Reel, and a Short) so its combined stats can be viewed together. A video belongs to at most one content group.

Manage via /api/v2/content-groups (list/create) and /api/v2/content-groups/{id} (get/patch/delete; add or remove members with add_video_ids / remove_video_ids). Combined stats: GET /api/v2/content-groups/{id}/stats returns summed totals plus a by_platform breakdown.

Campaign

Campaigns are mixed-platform: the creators and videos they contain can be on any platform, and stats roll up across all of them with a per-platform breakdown.

Goal

A per-creator performance target. Goals carry a platform scope so a target can apply to all of a creator's accounts, one platform, or one account.

Compliance is measured only over the accounts the scope includes. Create via POST /api/v2/creators/{id}/goals.

Context field conventions

Humans write free-text context for agents to read. The context field is readme across creators, campaigns, projects, and videos. It is the Notes field in the UI and is writable by agents via PATCH. On a video, the separate description field holds the post's original caption from the platform (not a notes field). Common patterns:

# Campaign readme
"Q1 creator push for Product X. Target: 1M views by March 31.
Top performers from last quarter: @creator1, @creator2.
Exclude any videos not directly about Product X."
 
# Creator readme
"Fitness creator, 3x/week posting cadence. Best content: workout tutorials.
Posts on TikTok and Instagram; YouTube is dormant.
Known issue: also posts food content unrelated to program: use selective mode.
Last contract renewal: Jan 2026."
 
# Video readme
"Strong outlier: 10x normal views. Trending audio #fitnesscheck helped.
Not representative of creator's normal performance."

When a context field contains explicit analysis instructions, follow them over your general analysis approach.

Conversion entities

Conversion Event

A project-scoped definition of an outcome worth tracking. Conversions reference it.

Plan limit max_conversion_events_per_project caps active event types (free 3, starter 25, ultra unlimited). Conversion volume is never capped.

Conversion

Attribution is frozen at receipt. Moving a video to another account later does not rewrite its past conversions. An org admin can explicitly override this per video.

Reading totals: filtering by creator_id returns conversions recorded against that creator's accounts and videos too. Do not sum across levels or you will double count.

Payout entities

Payout Method

Payout Structure

criteria_type values: recurring (flat-rate every period), goals (pays when creator meets their period goals), cpm (pays per 1,000 views on posts within the period), view_threshold (one-time bonus when an individual video crosses a view-count milestone, period and top-level amount_cents are null; each threshold defines its own amount).

Platform scope: a version's platform_scope (all | platform | account, default all) limits which of an assigned creator's accounts contribute, CPM impressions, goal compliance, and view-threshold crossings are all measured only from accounts in scope. When scoped, platform or account_id is set accordingly.

Payout Accrual

Computed by an hourly background job after relevant scrapers complete. Cannot be created via the API.

Payout Payment