reference meta graph api video insights gotchas 20260715T163743

Discovered during live backfill of Instagram + Facebook per-video data for CreatorTrack (ws 85, lib/instagram.ts, lib/facebook.ts):

  • Instagram has no video-duration field anywhere in the Graph API, confirmed by direct field probing. average_view_percentage must stay permanently NULL for IG (not derivable), only average_view_duration is available.
  • Facebook's legacy total_video_* insights fields are dead (always return 0). Real watch-time comes from post_video_avg_time_watched / post_video_view_time / blue_reels_play_count, and the last one is Reels-only.
  • Facebook's comments.summary(true) is permission-denied on the current system-user token, likely needs the pages_read_user_content scope. comments is documented in code as always-0 rather than silently retried.
  • Meta's error_subcode 2108006 ("Media Posted Before Business Account Conversion") is a permanent per-item condition on older posts; handle with a per-item null-degrade, not a batch-killing throw. Classify it by parsing the numeric error_subcode field from the full error body, not a substring match on a truncated snippet (truncation can push the subcode past the cutoff on verbose messages).

Why: these are Meta API behaviors, not CreatorTrack bugs, and re-discovering them via live probing costs real API calls and time. How to apply: when extending or debugging Instagram/Facebook video metrics ingestion anywhere in CreatorTrack, check lib/instagram.ts, lib/facebook.ts, and lib/social/errors.ts (extractJsonReasons) first; don't re-probe the API to rediscover these.

[auto-memory session 60d132de-4659-485c-8044-427af0ccce7f, confidence 0.72, mode staged]