Agent guide

This guide explains how an AI agent should connect to the trackagoat API and effectively analyze creator program data.

Getting started

Generate an API key

In the trackagoat UI, go to Org settings → API keys → + New API key. Give the key a name (e.g., Claude MCP access) and click Create. Copy the key immediately — it's shown once and cannot be recovered.

Verify connectivity

Call the schema endpoint to confirm the key works and orient yourself to the data model:

bash

curl -H "Authorization: Bearer tga_<key>" \
  https://www.trackagoat.com/api/v1/schema

List your projects

bash

curl -H "Authorization: Bearer tga_<key>" \
  https://www.trackagoat.com/api/v1/projects

Note the project_id values — you'll use them to filter creators, videos, and campaigns.

Reading description fields

Every entity (project, creator, video, campaign) has a description field intentionally designed for agent consumption.

Humans use these fields to leave context for agents:

Campaign description: strategy, target audience, performance benchmarks, analysis instructions
Creator description: niche, content focus, relationship notes, known issues
Video description: notes about why a video was tracked, content classification

Always read description fields before analyzing an entity. They may contain specific instructions, context that changes your interpretation of the data, or notes from a previous agent run.

The metadata field

Every creator, video, and campaign has a metadata field — an arbitrary JSON object ({} by default).

Designed for agent-attached structured data. Agents can use it to store:

Classifications: { "content_type": "tutorial", "sentiment": "positive" }
Scores: { "engagement_score": 8.4, "growth_score": 6.1 }
Previous analysis output: { "last_analysis": "2026-03-01", "summary": "..." }

The v1 API supports writing to readme fields (shown as Notes in the UI) via PATCH. Use this to store analysis summaries that humans and future agent sessions can read.

Recommended workflows

Analyze campaign performance

text

GET /api/v1/campaigns?project_id=<id>
  → Read each campaign's description for strategy context
  → GET /api/v1/campaigns/<id>/stats?from=<start>&to=<end>
  → Compare: top_videos, top_creators, history trend
  → Note: video_count_by_day shows content rollout pacing

Compare multiple campaigns by fetching stats for each over the same date range and comparing history series.

Find underperforming creators

text

GET /api/v1/creators?project_id=<id>
  → Sort by total_likes_count or follower_count (descending = top performers)
  → Check video_count — are they posting?
  → GET /api/v1/creators/<id>/stats → check posting_frequency for gaps
  → Read creator description for known context

Content analysis across a campaign

text

GET /api/v1/campaigns/<id>/stats
  → top_videos sorted by view_count — what's working?
GET /api/v1/videos?creator_id=<id>
  → Get all videos for a specific creator
  → Read each video's description for content notes

Trend analysis over time

text

GET /api/v1/creators/<id>/stats?from=<start>&to=<end>
  → history: follower growth trend
  → total_video_views: cumulative views trend
  → posting_frequency: weekly buckets — look for gaps

Pagination

All list endpoints use cursor-based pagination. Always paginate to completion before drawing conclusions:

javascript

async function fetchAll(url, key) {
  const items = [];
  let cursor = null;
  do {
    const u = cursor ? `${url}?cursor=${cursor}` : url;
    const { data, meta } = await fetch(u, {
      headers: { Authorization:

Important caveats

No real-time data. Stats are scraped on a schedule. Check last_scraped_at before drawing conclusions — stale data (> 12 hours old) may not reflect recent TikTok activity.
Current snapshots, not cumulative. follower_count, view_count etc. are the current snapshot values. Use stats history endpoints for trends.
Selective mode creators. When tracking_mode is selective, some videos may be in pending_review and not yet included in analytics.
Campaign stats are recursive. GET /campaigns/<id>/stats already aggregates all sub-campaigns — don't double-count.