Analytics & Derived Metrics

What are derived metrics?

Raw metrics (views, likes, followers) tell you absolute counts. Derived metrics are computed ratios — rates and velocities that let you compare performance across creators and campaigns of different sizes.

All derived metrics are computed server-side from your historical snapshot data using timezone-aware day bucketing. Request them by adding a metric= parameter to any stats endpoint.

Available metrics

Engagement rate by views (TikTok standard)

This is the primary TikTok engagement benchmark. It measures what percentage of viewers interacted with the content.

engagement_rate = (likes + comments + shares + saves) / views × 100

A null value means views were 0 on that day (divide-by-zero). Days with baseline snapshots contribute 0 to the engagement numerator and denominator.

curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v1/analytics?entity=creator&entity_id=<uuid>&metric=engagement_rate_by_views&from=2026-01-01&to=2026-03-31"

Engagement rate by followers (IG-style)

Used when you want to normalize engagement against audience size rather than reach. Useful for creator comparisons regardless of how often they post.

engagement_rate = (likes + comments + shares + saves) / follower_count × 100

The follower count used is the last known count as of each day (carry-forward). A null value means no follower data was available for that day.

This metric is not supported for individual videos — use creator or campaign entities.

curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v1/analytics?entity=creator&entity_id=<uuid>&metric=engagement_rate_by_followers&from=2026-01-01&to=2026-03-31"

Posts per week

Posting velocity normalized to a weekly rate, computed on a per-day granularity basis.

posts_per_week = posts_on_day × 7

A day with 0 posts returns 0.0 (a real rate of zero). null is returned only if there are no videos in scope at all.

curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v1/analytics?entity=creator&entity_id=<uuid>&metric=posts_per_week&from=2026-01-01&to=2026-03-31"

Average views per post

Views gained in the period divided by the number of posts published through that day. Shows whether new posts are increasing or hurting per-video efficiency.

avg_views_per_post = views_gained_on_day / videos_posted_through_day

null when no videos have been posted through that day yet.

curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v1/analytics?entity=campaign&entity_id=<uuid>&metric=avg_views_per_post&from=2026-01-01&to=2026-03-31"

Growth rate (period-over-period)

Day-over-day percentage change for any base metric. Pass base_metric to specify what to measure.

growth_rate = (value[day] − value[day−1]) / value[day−1] × 100

• First point in range always returns null (no prior).
• null when the prior day's value was 0 or missing.
• Supported base_metric values: views, likes, comments, shares, saves, followers (creator only), video_count (creator only).

# Views growth rate for a creator
curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v1/analytics?entity=creator&entity_id=<uuid>&metric=growth_rate_pop&base_metric=views&from=2026-01-01&to=2026-03-31"
 
# Follower growth rate
curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v1/analytics?entity=creator&entity_id=<uuid>&metric=growth_rate_pop&base_metric=followers&from=2026-01-01&to=2026-03-31"

Response shape

The /api/v1/analytics endpoint returns:

{
  "data": {
    "series": [
      {
        "entity_ref": { "type": "creator", "id": "uuid", "label": "@handle" },
        "metric": "engagement_rate_by_views",
        "unit": "percent",
        "mode": "rate",
        "granularity": "day",
        "timezone": "America/New_York"

Query parameters

Caching & freshness

All /api/v1/analytics responses are cached server-side for up to 5 minutes (300 seconds). This means:

• The first request after cache expiry runs the full resolver and may take 1–2 seconds.
• Subsequent requests within the 5-minute window return in under 50ms.
• The meta.cached field in each JSON response is true when data came from cache and false on a cold run.
• The meta.cache_ttl_seconds field is always 300.

When is cache invalidated?

The cache is tag-invalidated (not just TTL-expired) in these situations:

After a cache-busting event, the next request for affected data runs a fresh resolver. The maximum staleness in the worst case is 5 minutes (TTL alone), but in practice most data mutations trigger near-instant invalidation via the scraper webhook or inline revalidateTag calls.

Partial-bucket staleness

Today's in-progress bucket may be up to 5 minutes stale even with invalidation active — this is by design. The partial_bucket field tells you the as_of timestamp of the last data capture so you can show it to users.

Campaign analytics

Campaign analytics data is served from a pre-aggregated rollup that is rebuilt nightly and updated within ~5 minutes whenever a video is added to or removed from a campaign. Today's partial data may be up to a few minutes behind as changes propagate through the invalidation queue.

Historical saves values in older campaign snapshots may read as 0 — this is expected, as earlier snapshots did not record save counts.

Analytics controls

Every Analytics tab ships a shared toolbar that controls all charts on the panel simultaneously.

Date range presets

Presets beyond your plan's history window are disabled with an upgrade prompt. All time always works — it clamps automatically to the oldest data available on your plan and shows a notice like "Showing last 90 days (Free plan)."

Granularity

Controls the width of each time bucket. Choose from Auto, Day, Week, Month, Year, Cumulative, or Custom (N days).

• Auto selects the most readable granularity for the chosen range and displays the resolved value beneath the control (e.g., Auto — Week).
• Cumulative collapses the entire range into a single running-total line. When Cumulative granularity is active, mode is locked to Cumulative automatically.
• Custom reveals a numeric input (1–90) to define exact bucket width in days.

Mode

Rate-only metrics (engagement rate, growth rate) ignore this toggle — they always show rates.

Compare vs prior period

Toggle the vs prior period switch to overlay a second series shifted back by the same length as the selected range. This lets you see whether this week outperformed last week, or this month versus last month. The prior-period line renders dashed in a muted color alongside the primary series.

When compare is active, a row of Δ% summary cards appears above the charts showing the change for each metric versus the prior period:

• New mode (bar charts): shows the total delta — current-period sum vs prior-period sum
• Cumulative mode (area charts): shows the period gain — (last value − first value) for each window
• Rate/Engagement mode (line charts): shows the pp difference — current average rate minus prior average rate, expressed as ±X.Xpp rather than a percentage (since a percentage-of-a-percentage is misleading)

Partial-bucket exclusion

Today's bucket (and any in-progress bucket) is drawn dashed on the chart to indicate it's incomplete. It is excluded from the Δ% card calculation so partial data doesn't distort the summary. The prior-period equivalent of that bucket is also excluded, keeping the comparison fair.

Truncation

If the prior window extends before your tracking history or your plan's retention limit, the available prior period is automatically clamped. A muted notice appears below the toolbar indicating how many days of data were available versus requested — for example:

Prior period partial — 22 of 30 days available (before tracking started)

Hovering a dashed prior-period line in this state shows a tooltip with the same context.

Limitations

Retention by plan tier

Each plan tier has a maximum analytics history window:

In the UI

When you select a range that would exceed your tier's limit:

• Preset chips beyond your tier (e.g. "Last year" on Free) show a lock icon and are clickable to see the upgrade prompt.
• All time always works — it clamps to the oldest data available on your plan and shows a notice like "Showing last 90 days (your current plan). Upgrade for longer history." Clicking the notice opens the upgrade modal.
• Custom date picker allows choosing any range; if you pick a from date outside your window the API gate (below) will fire.

For API and agent callers

If you request a from date older than your plan's retention window, the unified endpoint returns HTTP 402:

{
  "data": null,
  "error": "Requested range exceeds plan retention window",
  "meta": {
    "code": "retention_exceeded",
    "limitKey": "stats_history_retention_days",
    "tier_retention_days": 90,
    "requested_from": "2025-01-01",
    "earliest_allowed": "2026-01-21"
  }
}

Use tier_retention_days from any successful response to pre-check the available window before issuing a long-range query.

Downgrade grace

When an org is downgraded to a lower tier, the previous tier's retention window remains in effect for 14 days to give users time to export data. After 14 days, the new tier's limit is enforced for both queries and the nightly data purge.

Multi-entity compare

On the Creator and Campaign analytics tabs you can overlay up to 5 entities on the same charts to compare performance side-by-side.

How to use it

What changes in overlay mode

• All count-mode charts switch to line mode — bars and filled areas are replaced with lines so N overlapping series stay readable.
• Engagement Rate still renders as a line (unchanged — it's rate-mode by default).
• Stacked engagement breakdown, Top Videos, and Top Creators panels are hidden — these are single-entity concepts.
• Baseline markers show only for your primary entity.
• The "vs prior period" compare switch is disabled while overlay is active. The two modes are mutually exclusive.

Shareable overlay URLs

The selected entity IDs are encoded in the URL as ?tbe=id1,id2,.... Copying the URL and sharing it with a teammate preserves the full overlay view — same date range, granularity, and selected entities.

Shareable URLs

All toolbar state (range preset, granularity, mode, compare toggle, and custom dates) is persisted in the page URL via short query parameters. Copy the URL from your browser's address bar to share an exact chart view with a teammate — they'll land on the same date range and settings.

The toolbar also saves your last-used settings per entity type (creator, campaign, video) in your browser's local storage, so your preferred range is restored when you navigate back to that tab.

engagement_rate_by_followers on video entities

Not supported — use creator or campaign entities instead.

growth_rate_pop with follower or video count base metrics

base_metric=followers and base_metric=video_count are only supported for creator entities.

Chart modes

New vs Cumulative

The Mode toggle changes how each time bucket is rendered:

Switching modes does not change the underlying data — only how it is displayed. Use New to spot spikes and posting cadence; use Cumulative to see growth trajectory.

Rate metrics

Metrics like Engagement Rate ignore the Mode toggle and always render as a line chart, since a rate is neither a delta nor a running total.

The Partial badge

When the most recent bucket covers a time period that hasn't ended yet (e.g., a weekly bucket mid-week), the chart shows a Partial · as of HH:mm TZ label above the chart. The in-progress bar or area is shaded to distinguish it from completed buckets.

Baseline markers

Vertical dotted lines on a chart mark when tracking first started for that entity (labeled Tracking started) or when a manual baseline snapshot was recorded (labeled Baseline). Data before a baseline marker represents the snapshot state, not necessarily change over time.

Breakdowns

The Breakdown button in each chart panel header lets you decompose a single aggregate series into its top constituent entities — up to 10, with everything else rolled into an Other segment.

How it works:

• Click the Breakdown button in any count-based chart (Total Views, Total Likes, Follower Count, Total Videos).
• The chart switches to a stacked-area view, showing each constituent as a colored band. Other is rendered in muted gray.
• Breakdown state is encoded in the URL (bdv=video, bdl=creator, etc.), so links are shareable.

Constraints:

• Breakdown is not available for rate metrics (Engagement Rate, Posts per Week, etc.). The button is disabled with a tooltip explaining why.
• Breakdown and period comparison (compare=prior_period) are mutually exclusive. Enabling comparison disables the breakdown menu.
• Breakdown and multi-entity overlay are mutually exclusive. The breakdown menu is disabled when two or more entities are overlaid.

Cohort velocity comparison

On the Video analytics tab, the View Velocity chart shows how many views a video gained per day after it was posted (day 0 = post date).

Toggle Compare to cohort to overlay two dashed reference lines:

• Creator avg — average views/day for up to 10 of the creator's most recent other videos.
• Org avg — average views/day for videos posted in the last 90 days across your entire organization.

Both lines show the number of videos in the cohort in the chart legend. If a creator has only published the current video, the creator avg line is hidden and a note is shown. Org avg always appears when there is data.

Stacked engagement breakdown

The Engagement Breakdown panel on Campaign and Video analytics shows Likes, Comments, Shares, and Saves as stacked segments. Each color maps to one metric. Use Mode: New to see engagement added per period, or Mode: Cumulative for total engagement over the range.

Engagement Rate panel

The Engagement Rate panel is available on Creator and Campaign tabs. It calculates:

(likes + comments + shares + saves) / views × 100

A value of 5% means roughly 1 in 20 views resulted in some form of engagement. This panel always renders as a line chart and is not affected by the Mode toggle.

Annotations

Annotations are event markers that appear as pins at the top of each analytics chart. They help you correlate metric changes with real-world events.

Types of annotations

Adding an annotation

1. Open any analytics chart panel.
2. Click the Annotations button in the top-right corner of the panel.
3. Click Add in the popover.
4. Fill in the title (required), date & time, and optional markdown notes.
5. Click Add annotation — the pin appears immediately on all charts in the tab.

Cascade behavior

Annotations follow a cascade-down model:

• A campaign-scoped annotation appears on Creator and Video tabs for members of that campaign.
• A creator-scoped annotation appears on Video tabs for videos by that creator.
• Cascaded annotations show a caption ("From campaign: Summer Launch") so you know their origin.

Video-scoped annotations do not cascade up — they stay local to that video's tab.

Show/hide auto annotations

Each chart panel has a toggle in the Annotations popover labeled Show auto annotations. When turned off, only your user-authored notes are shown. This preference is saved in the URL (?tbha=1) and local storage.

Chart pin markers

Each pin represents one or more annotations bucketed to the same time period. The badge shows how many. Click a pin to see all annotations in that bucket — title, timestamp, any markdown content, and the cascade source if applicable.