Read as Markdown · Use with an AI agent
Computed fields and formulas
These fields are arithmetic over returned source records. They are separate from source counters and from optional AI interpretations. A page-sized sample does not establish an account’s lifetime performance.
Full-profile page metrics
The computed object on supported profile/full bundles uses the posts returned by that call. For example, see TikTok, Instagram and X. The posts parameter is a desired maximum on one source page, not a request to crawl that many historical posts.
| Field | Calculation and unit | Missing-input behavior |
|---|---|---|
sample_size | Number of returned post rows, including rows with no usable metrics. | Zero for an empty page. |
metric_samples.M | Number of finite non-negative numeric values for metric M: likes, comments, shares or views. | Null, absent, negative, non-finite and string values are excluded. Numeric zero is included. |
averages.M | Sum of usable M values / metric_samples.M. Count per observed post; no rounding in this calculation. | Null when that metric has no usable values. Each metric has its own denominator. |
posting_window | Earliest and latest parseable ISO-looking published_at, falling back to created_at when published_at is null or absent. days = (latest − earliest) / 86,400,000 milliseconds. | posts_with_timestamps counts valid dates. start/end are null when none; days is null with fewer than two dates and zero if all valid dates coincide. |
observed_posts_per_day | (posts_with_timestamps − 1) / posting_window.days. Observed intervals per day. | Null unless the time span is positive. This is not a forecast or a total publishing rate. |
For each metric, lookup checks stats, then metrics, then the top-level post and uses the first usable alias. Likes: likes / like_count. Comments: comments / comments_count / comment_count. Shares: shares / share_count / retweets. Views: views / view_count / plays / video_views. A missing share count is not inferred from quotes or replies.
The calculation does not deduplicate or remove pinned posts. Source ordering and duplicated boundary rows can bias these values. Preserve the sample size and window with any exported metric.
Instagram engagement
instagram/engagement fetches one profile and one posts page. Its computed object contains:
| Field | Meaning |
|---|---|
followers | Usable current followers or follower_count, checked in stats, metrics, then the profile itself. |
posts_observed | All returned post rows. |
posts_with_both_metrics | Rows having both finite non-negative likes and comments. Likes aliases are likes / like_count; comments aliases are comments / comment_count / comments_count. Container precedence is stats, metrics, then the post. |
average_interactions | Mean of (likes + comments) over those paired rows; null if no pair is usable. |
engagement_rate_percent | 100 × average_interactions / followers. Null when followers are missing or zero, or the average is null. No rounding or clamp to 100 is applied. |
This is a percentage of current followers, not unique engaged people or a views-based rate. Interactions can exceed the follower population. There is no continuation for this fixed-sample operation; use the posts endpoints if you need a different explicitly collected sample.
Worked example with missing counts
[
{
"id": "a",
"created_at": "2026-09-01T12:00:00Z",
"stats": {
"likes": 10,
"comments": 2,
"shares": 0,
"views": 100
}
},
{
"id": "b",
"created_at": "2026-09-03T12:00:00Z",
"stats": {
"likes": null,
"comments": 5,
"shares": 1,
"views": 300
}
},
{
"id": "c",
"created_at": "2026-09-05T12:00:00Z",
"stats": {
"likes": 30,
"comments": 6,
"shares": null,
"views": null
}
}
]The page has sample_size=3. metric_samples is likes=2, comments=3, shares=2, views=2. Average likes=(10+30)/2=20; comments=(2+5+6)/3=4.333…; shares=(0+1)/2=0.5; views=(100+300)/2=200.
The posting window spans four days, so observed_posts_per_day=(3−1)/4=0.5. For Instagram engagement, only a and c contain both required counters: average_interactions=((10+2)+(30+6))/2=24. With 1,200 current followers, engagement_rate_percent=2. The missing like count on b is excluded.
YouTube channel analytics use a different denominator
youtube/profile/full can include analytics for the returned recent_videos page. It first limits the sample to videos with numeric view counts. Likes and comment samples are subsets of that view-count sample. No usable views yields analytics:null and a warning.
| Field | Formula and units |
|---|---|
sampled_videos | Number of videos with usable numeric views. metric_samples records counts for views, likes, comments and engagement separately. |
avg_views / avg_likes / avg_comments | Sum divided by the corresponding metric sample count, rounded with Math.round. Likes/comments are null when their sample is empty. |
engagement_rate | (sum likes + sum comments_count) / sum views, using only rows with all three counters. Rounded to six decimal places. This is a ratio, not a percentage; multiply by 100 to display percent. Null if that subset has zero total views. |
most_viewed_video_id | ID of the highest-view video within the view-count sample. Ties retain source order. |
Applied to the example counts above, the view sample contains a and b: avg_views=200, avg_likes=10, avg_comments=4. Only a has all three counters, so engagement_rate=12/100=0.12, displayed as 12%. The third video’s likes cannot contribute because its views are missing.
Keep recent_videos_pagination, warnings and missing detail indicators alongside these metrics. They describe this page, not the channel’s lifetime. Source-reported ratings, counters and ranks are not covered by these arithmetic formulas; read the relevant endpoint field reference.