Accounts

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

Field	Type	Description
`id`	uuid	Account ID
`creator_id`	uuid	Creator that owns this account
`project_id`	uuid	Project this account belongs to
`org_id`	uuid	Owning organization ID
`platform`	`tiktok` \| `instagram` \| `youtube`	Which platform this account is on
`handle`	string	Platform `@username`
`platform_user_id`	string \| null	The platform's internal user ID
`display_name`	string \| null	Display name from the platform
`avatar_url`	string \| null	Profile image URL
`bio_link`	string \| null	Link in the account's bio
`follower_count`	number	Current follower count (latest snapshot)
`following_count`	number	Current following count
`total_likes_count`	number	Cumulative total likes
`video_count`	number	Current total video count
`tracking_mode`	`auto` \| `selective`	`auto` — track all videos. `selective` — new videos land in the inbox.
`tracking_start_date`	YYYY-MM-DD \| null	Start of the tracked window
`tracking_end_date`	YYYY-MM-DD \| null	End of the tracked window (`null` = no end)
`is_active`	boolean	Whether the account is actively tracked
`last_scraped_at`	ISO 8601 \| null	When the account was last scraped
`created_at`	ISO 8601	When the account was added
`updated_at`	ISO 8601	Last 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

Parameter	Type	Default	Description
`project_id`	uuid	:	Filter to a specific project
`creator_id`	uuid	:	Filter to a specific creator
`platform`	`tiktok` \| `instagram` \| `youtube`	:	Filter to one platform
`search`	string	:	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

Field	Type	Default	Description
`platform`	`tiktok` \| `instagram` \| `youtube`	required	Which platform this account is on.
`handle`	string	required	Platform `@username` (1–60 chars). Leading `@` is stripped.
`tracking_mode`	`auto` \| `selective`	`auto`	Video discovery mode.

Responses

HTTP	Cause
201	Account added; body is the full account object.
402	`max_accounts_per_org` limit reached.
404	Creator 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

Field	Type	Description
`handle`	string	Rename the account handle (1–60 chars). Triggers a re-scrape.
`tracking_mode`	`auto` \| `selective`	Switch between auto-tracking and inbox review.
`tracking_start_date`	YYYY-MM-DD \| null	Start of the tracked window. `null` clears it.
`tracking_end_date`	YYYY-MM-DD \| null	End of the tracked window. `null` = no end.

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 field	Values	Description
`job_type`	`creator_profiles` \| `video_stats` \| `discover_videos`	Which scrape job to dispatch (optional).

The response echoes { job_type, account_id, job_id }.

HTTP	Cause
200	Scrape dispatched.
400	Account is disabled.
429	Daily 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

Parameter	Type	Default	Description
`from`	YYYY-MM-DD	:	Start of the range (inclusive)
`to`	YYYY-MM-DD	:	End of the range (inclusive)
`limit`	number	365	Max snapshots to return (max 1000)

Response fields

Each element of the returned array:

Field	Type	Description
`account_id`	uuid	Account this snapshot belongs to
`snapshot_at`	ISO 8601	When the snapshot was taken
`follower_count`	number \| null	Followers at snapshot time
`following_count`	number \| null	Following count at snapshot time
`total_likes_count`	number \| null	Cumulative likes at snapshot time
`video_count`

Creators

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

Creators & Accounts guide

How the multi-platform model works.