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 or Instagram; youtube is reserved for YouTube tracking, which isn't available yet). 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                        : readme (the organization's document)
  ├── Member(s)                     : each with a personalization document (readme)
  └── 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, is_active and metadata. 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, a Markdown document on the organization, every project, campaign, creator, video, payout method, payout structure and payout payment, and every member (their personalization document). It is the README or Notes in the app. Find them with GET /api/v2/notes (MCP list_notes), read one with GET /api/v2/notes/{entity_type}/{id} (get_notes), and add to one with POST /api/v2/notes/{entity_type}/{id} (update_notes), which appends by default and never overwrites what people wrote. Everyone in the organization, and their agents, can read every document. See Notes and documents. On a video, caption holds the post's text from the platform (read-only, not a notes field); the old description field is deprecated. 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; each period pays for the views each video gained since it was last paid, for view_lifetime_days after posting or forever), 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#