Videos

Since Trackagoat 2.0, videos are multi-platform. Each video carries a platform, belongs to an account, and records the platform's own platform_video_id. Add videos from TikTok, Instagram, or YouTube — the platform is auto-detected from the URL.

GET /api/v2/videos

List tracked videos in your organization. Videos with tracking_status = "excluded" are never returned.

Request

bash

curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v2/videos?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
`account_id`	uuid	:	Filter to a specific account
`platform`	`tiktok` \| `instagram` \| `youtube`	:	Filter to one platform
`content_group_id`	uuid	:	Filter to videos in a specific content group

Response fields

Field	Type	Description
`id`	uuid	Video ID
`project_id`	uuid	Project this video belongs to
`creator_id`	uuid \| null	Creator this video belongs to (null for direct adds)
`account_id`	uuid \| null	Account this video was posted from (null for direct adds)
`platform`	`tiktok` \| `instagram` \| `youtube`

POST /api/v2/projects//videos

Add one video URL or a bulk array (up to 50). Requires the write scope. The platform and video ID are auto-detected from the URL. Dispatches a video-stats scrape automatically.

bash

curl -X POST \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"url": "https://www.tiktok.com/@charlidamelio/video/7123456789"}' \
  "https://www.trackagoat.com/api/v2/projects/<projectId>/videos"

Bulk (up to 50), mixing platforms freely:

bash

-d '{"videos": [{"url": "https://www.tiktok.com/@user/video/111"}, {"url": "https://www.instagram.com/reel/ABC123/"}]}'

HTTP	Cause
201	Video(s) added.
402	Plan limit reached.
422	Could not detect the platform / video ID from the URL.

PATCH /api/v2/videos/

Update a video's metadata. At least one field is required. Requires the write scope.

bash

curl -X PATCH \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -d '{"readme": "Strong performance. Boosted by trending audio.", "tracking_status": "included"}' \
  https://www.trackagoat.com/api/v2/videos/<uuid>

Body

Field	Type	Description
`title`	string	Override the video title.
`description`	string	The post's caption. Editable, but normally set from the platform.
`readme`	string \| null	Team notes / agent context (Markdown). Pass `null` to clear.
`tracking_status`	string	One of `auto_tracked`, `pending_review`, `included`, `excluded`, `direct_add`.

DELETE /api/v2/videos/

Permanently delete a video. Requires the write scope.

bash

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

Returns { "deleted": true }.

POST /api/v2/videos//scrape

Trigger a manual video-stats scrape. Requires the write scope.

bash

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

The response echoes { video_id, job_id }. Returns 429 if the daily scrape limit is exceeded.

POST /api/v2/videos//tracking-disable

Disable tracking for a video without deleting it. Requires the write scope.

bash

curl -X POST -H "Authorization: Bearer tga_<key>" \
  https://www.trackagoat.com/api/v2/videos/<uuid>/tracking-disable

Use /tracking-enable to re-enable, and /tracking-unexempt to clear the age-rule exemption flag. Each returns the video's tracking flags: { id, tracking_disabled, tracking_disabled_at, tracking_disabled_reason, tracking_exempted }.

POST /api/v2/projects//videos/bulk-tracking-disable

Disable tracking for up to 200 videos in one call. Requires the write scope.

bash

curl -X POST \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -d '{"video_ids": ["<uuid1>", "<uuid2>"]}' \
  "https://www.trackagoat.com/api/v2/projects/<projectId>/videos/bulk-tracking-disable"

Use /bulk-tracking-enable to re-enable. Pass "exempt": true to also mark videos as exempt from auto-expiry.

Video time-series analytics

There is no per-video stats endpoint. Use the unified Analytics endpoint with entity=video for view, engagement, and growth time-series.

bash

# Daily new views for a video
curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v2/analytics?entity=video&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=video&entity_id=<uuid>&metric=engagement_rate_by_views&mode=rate"

To view combined stats for the same content across platforms, group the videos and read content group stats.

engagement_rate_by_followers is not supported for video entities — use a creator or campaign entity instead. See the Analytics API reference for the full metric and parameter list.