Creators

Since Trackagoat 2.0, a creator is a person or brand that owns one or more platform accounts (tiktok or instagram; the enum also accepts youtube, which is reserved and not supported). 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#

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

Query parameters#

Response fields#

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.

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#

Each object in accounts[]:

Responses#

The creator and all of its accounts are created together: on a 402 or 409 nothing is created, so you can fix the request and retry without leaving an empty creator behind.

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#

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

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 to 20) fields as POST /api/v2/creators. Returns 402 if the account limit is reached, 409 if a handle is already tracked in the project, and 404 if the project is not found.

Each creator in a batch is created together with its accounts, so a failing creator never leaves an empty creator behind. Creators earlier in the batch than the failing one are kept.

GET/api/v2/creators/#

Get a single creator with its accounts embedded.

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

Returns the same shape as a list item, plus readme_version: a version token for the creator's notes, needed to replace the notes safely. 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.

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

Body#

Returns 404 if the creator isn't found.

POST/api/v2/creators//notes#

Add to or replace a creator's notes (readme) without clobbering human edits. Requires the write scope. Accepts an Idempotency-Key header, so a retried append isn't added twice.

Append (recommended) adds content as a new section at the end, signed with the API key's name and your org's local date:

curl -X POST \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mode": "append", "content": "Views dropped 40% week over week."}' \
  https://www.trackagoat.com/api/v2/creators/<uuid>/notes

The notes then end with:

Views dropped 40% week over week.
 
*Added by Weekly review bot via API, 2026-10-08*

Replace overwrites the whole notes and requires the readme_version from your last GET /api/v2/creators/{id}. If the notes changed since that read, nothing is written and you get 409 notes_conflict:

-d '{"mode": "replace", "content": "Rewritten notes", "expected_readme_version": "9f2c4e1a7b3d5f60"}'

Body#

Response#

{
  "data": {
    "id": "uuid", "entity_type": "creator", "mode": "append", "changed": true,
    "readme": "…", "readme_version": "41d0c3b2a9e8f716", "previous_readme_version": "9f2c4e1a7b3d5f60"
  },
  "error": null,
  "meta": null
}

readme_version is a hash of the notes text, so it only changes when the notes do; scheduled scrapes don't cause conflicts. Each write is a compare-and-swap: if someone edits the notes while an append is being saved, the append is applied on top of their edit. Writes appear in the creator's change log as Internal notes updated.

DELETE/api/v2/creators/#

Soft-delete a creator (sets is_active = false). The creator's accounts are removed with it, so they stop being scraped and no longer count toward max_accounts_per_org. The creator's history and data are preserved, and you can add the same handles again later. Requires the write scope.

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 the creator's primary account is scraped (its TikTok account if it has one, otherwise its earliest-added active account); pass ?account_id=<uuid> to scrape a specific account. Returns 400 if the creator has no active account. Consumes from the org's daily manual-scrape quota. Requires the write scope.

# Scrape the creator's primary account
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>"

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

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.

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). Each creator is removed exactly as with DELETE /api/v2/creators/{id}, including its accounts. Requires the write scope.

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"

Returns { "removed_count": N }, the number of creators actually removed. IDs that are unknown, already removed, or in another project are skipped and not counted.

Analytics (time-series)#

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

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