trackagoat logotrackagoat/Docs

Command Palette

Search for a command to run...

Getting started

  • Welcome
  • Quickstart
  • Core concepts

Guides

  • Creators & Accounts
  • Creators
  • Instagram tracking
  • YouTube tracking
  • Videos
  • Campaigns
  • Creator Goals
  • Tracking Inbox
  • Content calendar
  • How scraping works
  • Analytics & metrics
  • Similar creator pools
  • Over-posting & suppression
  • Program Health
  • Sentiment Radar
  • API keys
  • Limits & plan tiers
  • Notifications
  • Payouts
  • Shareable creator pages
  • Conversions

API reference

  • Overview
  • Authentication
  • Errors
  • Projects
  • Creators
  • Accounts
  • Share Links
  • Videos
  • Content Groups
  • Campaigns
  • Analytics
  • Aggregate Analytics
  • Goal Compliance
  • Payouts
  • Conversions
  • Schema

For agents

  • Agent guide
  • Data model
  • MCP & tooling

Platform

  • Brand
  • Changelog
  • Support
DocsAPI reference

Creators

List, add, update, and remove creators. Each creator owns one or more platform accounts.

PreviousProjectsNextAccounts

On this page

  • GET /api/v2/creators
  • Request
  • Query parameters
  • Response fields
  • Share links
  • POST /api/v2/creators
  • Body
  • Responses
  • POST /api/v2/projects/{projectId}/creators
  • Single creator
  • Batch (up to 50)
  • GET /api/v2/creators/{id}
  • PATCH /api/v2/creators/{id}
  • Body
  • DELETE /api/v2/creators/{id}
  • POST /api/v2/creators/{id}/scrape
  • POST /api/v2/projects/{projectId}/creators/bulk-reenable
  • POST /api/v2/projects/{projectId}/creators/bulk-remove
  • Analytics (time-series)

Since Trackagoat 2.0, a creator is a person or brand that owns one or more platform accounts (tiktok, instagram, youtube). A creator has no handle of its own. It embeds an accounts[] array and exposes a derived top-level handle (the primary account's handle: TikTok first, else the earliest-created active account). Handle and tracking configuration live on the account. See Accounts.

GET /api/v2/creators

List creators being tracked in your organization, with their accounts embedded.

Request

bash
curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v2/creators?project_id=<uuid>"

Query parameters

ParameterTypeDefaultDescription
project_iduuid:Filter to a specific project
platformtiktok | instagram | youtube:Only creators with an account on this platform
searchstring:Partial match on creator display name or any account handle
limitnumber50Items per page (max 100)
cursorstring:Pagination cursor

Response fields

FieldTypeDescription
iduuidCreator ID
project_iduuidProject this creator belongs to
org_iduuidOwning organization ID
display_namestring | nullCreator display name
handlestring | nullPrimary account's handle (derived, TikTok first, else earliest)
avatar_url

Creator-level counts are the sum across the creator's accounts. Add an Instagram account and the creator's follower total grows to include it.

Share links

share_link carries the creator's shareable page — the URL is always {site}/share/creator/{creator_id}, so you can construct it from any creator id without a lookup.

The entrance pin is omitted unless the request passes include_pin=true and the key holds the admin scope; anything else returns 403 insufficient_scope. See Share Links for the full rules and the management endpoints.

POST /api/v2/creators

Create a creator with one or more accounts (at least one is required). Requires the write scope. Dispatches a profile + discovery scrape automatically: the scraper fans out to every account.

bash
curl -X POST \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "project_id": "<uuid>",
    "display_name": "Charli",
    "accounts": [
      {"platform": "tiktok", "handle": "charlidamelio"},
      {"platform": "instagram", "handle": "charlidamelio", "tracking_mode": "selective"}
    ]
  }' \
  "https://www.trackagoat.com/api/v2/creators"

Body

FieldTypeDefaultDescription
project_iduuidrequiredProject to create the creator in.
display_namestringfirst account's handleCreator display name (max 100 chars).
metadataobject{}Arbitrary JSON for your own identifiers, so an external system can map its records back to this creator. Also settable later via PATCH, which replaces the whole object rather than merging.
accountsarrayrequired

Each object in accounts[]:

FieldTypeDefaultDescription
platformtiktok | instagram | youtuberequiredWhich platform this account is on.
handlestringrequiredPlatform @username (1–60 chars). Leading @ is stripped.
tracking_modeauto | selective | hashtagauto

Responses

HTTPCause
201Creator created; body is the full creator with embedded accounts[].
402max_accounts_per_org limit reached (accounts, not creators, are counted).
403Key lacks the write scope.
404Project not found (or not in your org).

POST /api/v2/projects//creators

Add one creator or a batch (up to 50) to a specific project. Requires the write scope. Each creator carries an accounts[] array (min 1).

Single creator

bash
curl -X POST \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"accounts": [{"platform": "tiktok", "handle": "charlidamelio"}]}' \
  "https://www.trackagoat.com/api/v2/projects/<projectId>/creators"

Batch (up to 50)

bash
curl -X POST \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "creators": [
      {"accounts": [{"platform": "tiktok", "handle": "charlidamelio"}]},
      {"display_name": "Khaby", "accounts": [{"platform": "tiktok", "handle": "khaby.lame", "tracking_mode": "selective"}]}
    ]
  }' \
  "https://www.trackagoat.com/api/v2/projects/<projectId>/creators"

Each creator object accepts the same display_name (optional), metadata (optional) and accounts[] (1–20) fields as POST /api/v2/creators. Returns 402 if the account limit is reached and 404 if the project is not found.

GET /api/v2/creators/

Get a single creator with its accounts embedded.

bash
curl -H "Authorization: Bearer tga_<key>" \
  https://www.trackagoat.com/api/v2/creators/<uuid>

Returns the same shape as a list item. 404 if the creator doesn't exist or isn't in your org.

PATCH /api/v2/creators/

Update creator-level fields only. At least one field is required. Requires the write scope.

Handles and tracking configuration live on accounts, not creators. To rename a handle or change tracking settings, use PATCH /api/v2/accounts/{id}.

bash
curl -X PATCH \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -d '{"readme": "Focus on cooking content. Posts Tues/Thurs.", "is_active": true}' \
  https://www.trackagoat.com/api/v2/creators/<uuid>

Body

FieldTypeDescription
display_namestringOverride the display name (max 100 chars).
readmestring | nullMarkdown notes visible in the UI. Pass null to clear.
is_activebooleanActivate or deactivate the creator.
metadataobjectArbitrary JSON. Replaces the whole object — read the current value first if you need to preserve existing keys.

Returns 404 if the creator isn't found.

DELETE /api/v2/creators/

Soft-delete a creator (sets is_active = false). The creator's history and data are preserved. Requires the write scope.

bash
curl -X DELETE \
  -H "Authorization: Bearer tga_<key>" \
  https://www.trackagoat.com/api/v2/creators/<uuid>

Returns { "deleted": true }.

POST /api/v2/creators//scrape

Trigger a manual scrape for a creator. By default every account under the creator is scraped; pass ?account_id=<uuid> to scrape only a single account. Consumes from the org's daily manual-scrape quota. Requires the write scope.

bash
# Scrape all accounts
curl -X POST \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -d '{"job_type": "discover_videos"}' \
  https://www.trackagoat.com/api/v2/creators/<uuid>/scrape
 
# Scrape a single account
curl -X POST \
  -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v2/creators/<uuid>/scrape?account_id=<accountUuid>"
FieldWhereValuesDescription
account_idqueryuuidRestrict the scrape to one account.
job_typebodycreator_profiles | video_stats | discover_videosWhich scrape job to dispatch.

The response echoes { job_type, creator_id, account_id, job_id } (account_id is null when scraping all accounts).

HTTPCause
200Scrape dispatched.
400Creator is inactive.
429Daily scrape limit exceeded.

POST /api/v2/projects//creators/bulk-reenable

Re-enable creators that were automatically disabled. Requires the write scope. Subject to the 24-hour cooldown per creator.

bash
curl -X POST \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -d '{"creator_ids": ["<uuid1>", "<uuid2>"]}' \
  "https://www.trackagoat.com/api/v2/projects/<projectId>/creators/bulk-reenable"

Returns { ok_count, skipped_count, failed_count }.

POST /api/v2/projects//creators/bulk-remove

Soft-delete multiple creators in one call (max 100). Requires the write scope.

bash
curl -X POST \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -d '{"creator_ids": ["<uuid1>", "<uuid2>"]}' \
  "https://www.trackagoat.com/api/v2/projects/<projectId>/creators/bulk-remove"

Analytics (time-series)

Creator time-series analytics live on the unified endpoint. Add &platform= to scope a creator's series to a single platform.

bash
# Views for a creator: daily new, last 30 days
curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v2/analytics?entity=creator&entity_id=<uuid>&metric=views&mode=new&granularity=day"
 
# Engagement rate (derived)
curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v2/analytics?entity=creator&entity_id=<uuid>&metric=engagement_rate_by_views&mode=rate"
 
# Multi-entity overlay: compare up to 5 creators side-by-side
curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v2/analytics?entity=creator&entity_ids=<uuid1>,<uuid2>&metric=views&granularity=week"

See the Analytics API reference for the full parameter and response documentation, and Accounts for per-account follower history.

include_pin
boolean
false
Include entrance PINs in share_link. Requires the admin scope; 403 otherwise
string | null
Profile image URL
readmestring | nullMarkdown notes (rendered in the Notes tab)
metadataobjectAgent-writable structured data ({} by default)
is_activebooleanWhether the creator is actively tracked
follower_countnumber | nullFollowers summed across the creator's accounts
following_countnumber | nullFollowing count summed across accounts
total_likes_countnumber | nullCumulative likes summed across accounts
video_countnumber | nullTotal video count summed across accounts
accountsarrayThe creator's platform accounts. See Accounts
share_linkobject | nullThe creator's PIN-gated public page, or null if they don't have one. See Share Links
created_atISO 8601When creator was added
updated_atISO 8601Last update
1–20 account objects (see below).
auto: track all videos. selective: new videos land in the inbox for review. hashtag: auto-track videos whose caption contains a tracked hashtag.
tracking_hashtagsstring[][]Required (non-empty) when tracking_mode is hashtag. Normalized server-side and by a database trigger: NFC + lowercase, leading # stripped, and characters that can't appear in a hashtag removed (#Black-Friday becomes blackfriday). Whitespace and commas separate tags. Max 50 tags, 100 chars each.
hashtag_inbox_non_matchingbooleantrueHashtag mode: inbox non-matching videos (true) or exclude them (false).
tracking_start_dateYYYY-MM-DDtodayStart of the tracked window.
tracking_end_dateYYYY-MM-DD:Optional end date (must be ≥ start date).