Creators

GET /api/v1/creators

List creators being tracked in your organization.

Request

bash

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

Query parameters

Parameter	Type	Default	Description
`project_id`	uuid	—	Filter to a specific project
`search`	string	—	Partial match on TikTok handle
`limit`	number	50	Items per page (max 100)
`cursor`	string	—	Pagination cursor

Response fields

Field	Type	Description
`id`	uuid	Creator ID
`project_id`	uuid	Project this creator belongs to
`tiktok_handle`	string	TikTok `@username`
`display_name`	string \| null	Display name from TikTok
`description`	string \| null	Team notes / agent context

PATCH /api/v1/creators/

Update a creator's notes (readme) or TikTok handle (tiktok_handle). At least one field is required.

Request — update notes

bash

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

Request — rename handle

bash

curl -X PATCH \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -d '{"tiktok_handle": "newhandle"}' \
  https://www.trackagoat.com/api/v1/creators/<uuid>

Body

Field	Type	Description
`readme`	string \| null	Markdown notes. Pass `null` to clear.
`tiktok_handle`	string	New TikTok handle. 1–30 chars, letters/digits/`.`/`_`/`-`. Leading `@` is stripped automatically.

Renaming a handle

When you rename a handle, the following happens automatically:

Profile data (display name, avatar, bio, follower count) is cleared and repopulated by the next scrape (usually within a few minutes).
Tracked videos, past payouts, campaign memberships, notes, and README remain attached to the creator.
The rename is logged in the creator's History tab.
A fresh profile scrape is queued immediately.

Rename error responses

HTTP	`error` message	Cause
409	`handle_taken`	Another active creator in the same project already has that handle (case-insensitive).
409	`creator_banned`	The new handle is banned on this platform.
409	`invalid_handle`	Handle fails format validation (length or invalid characters).
409	`no_change`	The new handle is identical to the current one.

Analytics (time-series)

Creator time-series analytics have moved to the unified endpoint.

bash

# Views for a creator — daily new, last 30 days
curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v1/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/v1/analytics?entity=creator&entity_id=<uuid>&metric=engagement_rate_by_views&mode=rate"
 
# Prior-period comparison
curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v1/analytics?entity=creator&entity_id=<uuid>&metric=views&compare=prior_period"
 
# Multi-entity overlay — compare up to 5 creators side-by-side
curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v1/analytics?entity=creator&entity_ids=<uuid1>,<uuid2>&metric=views&granularity=week"

See the Analytics API reference for the full parameter and response documentation.

Removed: GET /api/v1/creators/{id}/stats returned 410 Gone as of v1.2. Use GET /api/v1/analytics?entity=creator&entity_id={id} instead.