Data model

Hierarchy

text

Organization
  └── Project(s)
        ├── Creator(s)   — TikTok accounts
        │     └── Video(s) — videos from this creator
        ├── Video(s)     — standalone videos added by URL
        └── 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.

Entity reference

Project

Field	Type	Notes
`id`	uuid
`name`	string
`description`	string \| null	Agent context — read before analyzing
`org_id`	uuid
`created_at`	ISO 8601
`updated_at`	ISO 8601

Creator

Field	Type	Notes
`id`	uuid
`project_id`	uuid
`tiktok_handle`	string	Without `@`
`display_name`	string \| null	From TikTok
`description`	string \| null	Agent context — read before analyzing
`metadata`

When tracking_mode is selective, some recent videos may be in pending_review and excluded from stats until reviewed.

Video

Field	Type	Notes
`id`	uuid
`creator_id`	uuid \| null	Null for direct-add videos
`url`	string	Full TikTok URL
`description`	string \| null	Agent context
`metadata`	object	Agent-writable
`view_count`	number

excluded videos are never returned by the API.

Campaign

Field	Type	Notes
`id`	uuid
`project_id`	uuid
`name`	string
`description`	string \| null	Agent context — strategy, benchmarks, instructions
`metadata`	object	Agent-writable
`created_at`	ISO 8601

Campaigns can contain sub-campaigns. /campaigns/<id>/stats recursively aggregates the full tree.

Description field conventions

Humans write description fields to communicate context to agents. Common patterns:

text

# Campaign description
"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 description
"Fitness creator, 3x/week posting cadence. Best content: workout tutorials.
Known issue: also posts food content unrelated to program — use selective mode.
Last contract renewal: Jan 2026."
 
# Video description  
"Strong outlier — 10x normal views. Trending audio #fitnesscheck helped.
Not representative of creator's normal performance."

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

Payout entities

Payout Method

Field	Type	Notes
`id`	uuid
`org_id`	uuid
`name`	string	e.g. "Venmo", "Cash App"
`icon_url`	string \| null	Public icon URL
`is_default`	boolean	Auto-seeded defaults cannot be deleted
`is_active`	boolean

Payout Structure

Field	Type	Notes
`id`	uuid
`project_id`	uuid
`name`	string
`is_active`	boolean	Archived structures stop generating accruals
`current_version`	object	Active rule snapshot: `period`, `amount_cents`, `currency`, `criteria_type`, ,

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).

Payout Accrual

Computed by an hourly cron (:15 past each hour) after relevant scrapers complete. Cannot be created via the API.

Field	Type	Notes
`id`	uuid
`creator_id`	uuid
`structure_id`	uuid
`structure_version_id`	uuid	The rule version active at period end (pinned)
`period_start_at`	ISO 8601	Inclusive, UTC
`period_end_at`	ISO 8601

To find unpaid accruals for a creator: GET /api/v1/payout-accruals?creator_id=<id>&status=earned

Payout Payment

Field	Type	Notes
`id`	uuid
`project_id`	uuid
`creator_id`	uuid \| null	Null for ad-hoc payments
`method_id`	uuid \| null
`method_name_snapshot`	string \| null	Captured at write time
`total_amount_cents`	number

Use auto_apply_outstanding: true on POST to settle all earned accruals for a creator in one call. Set Idempotency-Key header to safely retry.

criteria_params

proration_mode