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

Accounts

Platform accounts owned by a creator. List, add, update, remove, scrape, and read follower history.

PreviousCreatorsNextShare Links

On this page

  • Account fields
  • GET /api/v2/accounts
  • Query parameters
  • GET /api/v2/creators/{id}/accounts
  • POST /api/v2/creators/{id}/accounts
  • Body
  • Responses
  • GET /api/v2/accounts/{id}
  • PATCH /api/v2/accounts/{id}
  • Body
  • DELETE /api/v2/accounts/{id}
  • POST /api/v2/accounts/{id}/scrape
  • GET /api/v2/accounts/{id}/stats
  • Query parameters
  • Response fields

An account is a single platform presence: a TikTok, Instagram, or YouTube handle: owned by a creator. Tracking configuration (the handle, tracking_mode, and the tracked date window) lives on the account, and videos hang off accounts. Plan limits count accounts, since accounts are what actually get scraped.

Account fields

FieldTypeDescription
iduuidAccount ID
creator_iduuidCreator that owns this account
project_iduuidProject this account belongs to
org_iduuidOwning organization ID
platformtiktok | instagram | youtubeWhich platform this account is on
handlestringPlatform @username
platform_user_idstring | nullThe platform's internal user ID
display_namestring | nullDisplay name from the platform
avatar_urlstring | nullProfile image URL
bio_linkstring | nullLink in the account's bio
follower_countnumberCurrent follower count (latest snapshot)
following_countnumberCurrent following count
total_likes_countnumberCumulative total likes
video_countnumberCurrent total video count
tracking_modeauto | selective | hashtagauto: track all videos. selective: new videos land in the inbox. hashtag: track videos whose caption contains a tracked hashtag.
tracking_hashtagsstring[]Hashtag-mode only. 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_matchingbooleanHashtag-mode only. true (default) sends non-matching videos to the inbox; false excludes them.
tracking_start_dateYYYY-MM-DD | nullStart of the tracked window
tracking_end_dateYYYY-MM-DD | nullEnd of the tracked window (null = no end)
is_activebooleanWhether the account is actively tracked
last_scraped_atISO 8601 | nullWhen the account was last scraped
created_atISO 8601When the account was added
updated_atISO 8601Last update

GET /api/v2/accounts

List accounts across your organization.

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

Query parameters

ParameterTypeDefaultDescription
project_iduuid:Filter to a specific project
creator_iduuid:Filter to a specific creator
platformtiktok | instagram | youtube:Filter to one platform
searchstring:Partial match on handle

Returns a paginated array of account objects.

GET /api/v2/creators//accounts

List all accounts belonging to a single creator (ordered oldest first).

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

Returns an array of account objects. 404 if the creator doesn't exist or isn't in your org.

POST /api/v2/creators//accounts

Add a platform account to an existing creator and dispatch a scrape. Requires the write scope. Enforces the per-org account limit.

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

Body

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

Responses

HTTPCause
201Account added; body is the full account object.
402max_accounts_per_org limit reached.
404Creator not found (or not in your org).

GET /api/v2/accounts/

Get a single account.

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

Returns an account object. 404 if not found.

PATCH /api/v2/accounts/

Rename the handle or change tracking configuration. At least one field is required. Requires the write scope. Changing the handle dispatches a re-scrape of the account's profile and videos.

bash
curl -X PATCH \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -d '{"handle": "charlidamelio", "tracking_mode": "selective"}' \
  https://www.trackagoat.com/api/v2/accounts/<uuid>

Body

FieldTypeDescription
handlestringRename the account handle (1–60 chars). Triggers a re-scrape.
tracking_modeauto | selective | hashtagSwitch between auto-tracking, inbox review, and hashtag matching.
tracking_hashtagsstring[]Replace the tracked hashtag list. Must be non-empty if the resulting mode is hashtag.
hashtag_inbox_non_matchingbooleanRoute non-matching videos to the inbox or exclude them.

Returns the updated account object. 404 if not found.

DELETE /api/v2/accounts/

Soft-delete an account (its history and videos are preserved). Requires the write scope.

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

Returns { "deleted": true }.

POST /api/v2/accounts//scrape

Trigger a manual scrape for a single account. Consumes from the org's daily manual-scrape quota. Requires the write scope.

bash
curl -X POST \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -d '{"job_type": "video_stats"}' \
  https://www.trackagoat.com/api/v2/accounts/<uuid>/scrape
Body fieldValuesDescription
job_typecreator_profiles | video_stats | discover_videosWhich scrape job to dispatch (optional).

The response echoes { job_type, account_id, job_id }.

HTTPCause
200Scrape dispatched.
400Account is disabled.
429Daily scrape limit exceeded.

GET /api/v2/accounts//stats

Get an account's follower/stat snapshot history. This series is append-only: snapshots are only ever inserted, never updated.

bash
curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v2/accounts/<uuid>/stats?from=2026-01-01&to=2026-03-31"

Query parameters

ParameterTypeDefaultDescription
fromYYYY-MM-DD:Start of the range (inclusive)
toYYYY-MM-DD:End of the range (inclusive)
limitnumber365Max snapshots to return (max 1000)

Response fields

Each element of the returned array:

FieldTypeDescription
account_iduuidAccount this snapshot belongs to
snapshot_atISO 8601When the snapshot was taken
follower_countnumber | nullFollowers at snapshot time
following_countnumber | nullFollowing count at snapshot time
total_likes_countnumber | nullCumulative likes at snapshot time
video_count

Creators

Creators own accounts, create, list, and manage them.

Creators & Accounts guide

How the multi-platform model works.

limitnumber50Items per page (max 100)
cursorstring:Pagination cursor
Video discovery mode.
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: route non-matching videos to the inbox (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).
tracking_start_dateYYYY-MM-DD | nullStart of the tracked window. null clears it.
tracking_end_dateYYYY-MM-DD | nullEnd of the tracked window. null = no end.
number | null
Total video count at snapshot time
is_baselinebooleanWhether this is the initial baseline snapshot