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`

PATCH /api/v1/videos/

Update a video's readme field.

Request

bash

curl -X PATCH \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -d '{"readme": "Strong performance driven by trending audio. Boosted by creator\u2019s pinned post."}' \
  https://www.trackagoat.com/api/v1/videos/<uuid>

Body

Field	Type	Description
`readme`	string \| null	Markdown notes. Pass `null` to clear.

Derived metrics — GET /api/v1/videos//stats?metric=

When metric= is specified, the endpoint returns a computed time-series instead of the legacy shape.

Additional query parameters

Parameter	Type	Default	Description
`metric`	string	—	Derived metric ID. Omit for legacy response.
`granularity`	`day`	`day`	Currently day-only; other values return 400.
`tz`	IANA string	org setting	Timezone for day bucketing.
`base_metric`	string	—	Required for `growth_rate_pop`.

Supported metrics for video

Metric ID	`unit`	Notes
`engagement_rate_by_views`	`percent`	`(likes+comments+shares+saves)/views×100`
`growth_rate_pop`	`percent`	Δ% from prior day. Requires `base_metric=views\|likes\|comments\|shares\|saves`.

engagement_rate_by_followers is not supported for video entities — use a creator or campaign endpoint instead.

Response (metric= present)

json

{
  "data": {
    "series": [
      {
        "metric": "engagement_rate_by_views",
        "unit": "percent",
        "mode": "rate",
        "granularity": "day",
        "timezone": "America/New_York",
        "points": [
          { "bucket_start": "2026-01-01", "value": 6.5 },
          {

value is null for divide-by-zero or missing data. The first growth_rate_pop point is always null.

Cohort velocity — GET /api/v1/videos//stats?cohort=1

Add ?cohort=1 to the legacy stats endpoint to overlay two cohort reference series in the cohort response field. This is only meaningful when used without metric= (the legacy shape).

Additional query parameter

Parameter	Type	Default	Description
`cohort`	boolean	`false`	When `1`, include creator avg and org avg velocity cohorts.

Response additions

json

{
  "data": {
    "velocity": [{ "day_number": 0, "views_gained": 5200 }],
    "cohort": {
      "creator_avg": [
        { "day_number": 0, "avg_views_gained": 3800, "sample_size": 8 }
      ],
      "org_avg": [
        { "day_number": 0, "avg_views_gained":

cohort is omitted when ?cohort=1 is not passed or when the video has no creator_id.

sample_size is the number of distinct videos contributing to each average at that day number. It can decrease at higher day numbers as fewer videos have that many days of history.