GET /api/v1/creators
List creators being tracked in your organization.
Request
curl -H "Authorization: Bearer tga_<key>" \ "https://www.trackagoat.com/api/v1/creators?project_id=<uuid>" Query parameters
Parameter Type Default Description project_iduuid : Filter to a specific project searchstring : Partial match on TikTok handle limitnumber 50 Items per page (max 100) cursorstring : Pagination cursor
Response fields
Field Type Description iduuid Creator ID project_iduuid Project this creator belongs to tiktok_handlestring TikTok @username display_namestring | null Display name from TikTok descriptionstring | null Team notes / agent context
POST /api/v1/projects//creators
Add one creator or a bulk array (up to 50). Requires the write scope. Dispatches a discover-videos scrape automatically.
Single creator
curl -X POST \ -H "Authorization: Bearer tga_<key>" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $( uuidgen )" \ -d '{"tiktok_handle": "charlidamelio", "tracking_mode": "auto"}' \ "https://www.trackagoat.com/api/v1/projects/<projectId>/creators" Bulk create (up to 50)
curl -X POST \ -H "Authorization: Bearer tga_<key>" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $( uuidgen )" \ -d '{"creators": [{"tiktok_handle": "charlidamelio"}, {"tiktok_handle": "khaby.lame", "tracking_mode": "selective"}]}' \ "https://www.trackagoat.com/api/v1/projects/<projectId>/creators" Body fields
Field Type Default Description tiktok_handlestring required TikTok @username. Leading @ is stripped. tracking_modeauto | selectiveautoauto — track all videos. selective — new videos land in the inbox for review.tracking_start_dateYYYY-MM-DD today Start of the tracked window.
Side effects
A creator_profiles + discover_videos scrape is queued immediately.
The creator appears in the project's creator list within seconds.
If the handle was previously removed, the creator is reactivated (returns HTTP 200, not 201).
PATCH /api/v1/creators/
Update a creator's metadata or tracking settings. 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.", "tracking_mode": "selective"}' \ https://www.trackagoat.com/api/v1/creators/ < uui d > Body
Field Type Description tiktok_handlestring Rename the creator. See renaming notes below. display_namestring Override the display name. descriptionstring Short notes or agent context (max 5 000 chars). readmestring | null Markdown notes visible in the UI. Pass null to clear. tracking_modeauto | selective
Renaming a handle
When you change tiktok_handle, profile data is re-scraped automatically and a handle_changed event is written to the creator's history. Videos, goals, payouts, and README remain intact.
HTTP meta.codeCause 409 handle_takenAnother active creator in this project already has that handle. 409 creator_bannedThe new handle is globally banned.
DELETE /api/v1/creators/
Soft-delete a creator (sets is_active = false). The creator's history and data are preserved. Requires the write scope.
curl -X DELETE \ -H "Authorization: Bearer tga_<key>" \ https://www.trackagoat.com/api/v1/creators/ < uui d > Trigger a manual scrape for a creator. Consumes from the org's daily manual-scrape quota. Requires the write scope.
curl -X POST \ -H "Authorization: Bearer tga_<key>" \ -H "Content-Type: application/json" \ -d '{"job_type": "discover_videos"}' \ https://www.trackagoat.com/api/v1/creators/ < uui d > /scrape Body field Values Default Description job_typecreator_profiles | video_stats | discover_videoscreator_profilesWhich scrape job to dispatch.
POST /api/v1/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/v1/projects/<projectId>/creators/bulk-reenable" Returns { ok_count, skipped_count, failed_count }.
POST /api/v1/projects//creators/bulk-remove
Soft-delete multiple creators in one call (max 100). 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/v1/projects/<projectId>/creators/bulk-remove" Analytics (time-series)
Creator time-series analytics have moved to the unified endpoint.
# 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.
