Videos

GET /api/v1/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/v1/videos?project_id=<uuid>"

Query parameters

Parameter	Type	Default	Description
`project_id`	uuid	:	Filter to a specific project
`creator_id`	uuid	:	Filter to a specific creator
`limit`	number	50	Items per page (max 100)
`cursor`	string	:	Pagination cursor

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)
`tiktok_video_id`	string	TikTok's internal video ID
`url`	string	Full TikTok URL
`title`

POST /api/v1/projects//videos

Add one TikTok video URL or a bulk array (up to 50). Requires the write scope. 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/v1/projects/<projectId>/videos"

Bulk:

bash

-d '{"videos": [{"url": "https://www.tiktok.com/@\u2026/video/111"}, {"url": "https://www.tiktok.com/@\u2026/video/222"}]}'

PATCH /api/v1/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/v1/videos/<uuid>

Body

Field	Type	Description
`title`	string	Override the video title.
`description`	string	Short notes (max 5 000 chars).
`readme`	string \| null	Markdown notes. Pass `null` to clear.
`tracking_status`	string	One of `auto_tracked`, `included`, `excluded`, `direct_add`.

DELETE /api/v1/videos/

Permanently delete a video. Requires the write scope.

bash

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

POST /api/v1/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/v1/videos/<uuid>/scrape

POST /api/v1/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/v1/videos/<uuid>/tracking-disable

Use /tracking-enable to re-enable, and /tracking-unexempt to remove the exemption flag.

POST /api/v1/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/v1/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/v1/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/v1/analytics?entity=video&entity_id=<uuid>&metric=engagement_rate_by_views&mode=rate"

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.