Performance analytics

Read post metrics with explicit measurement windows, coverage, availability and freshness.

Read post performance

Analytics report published destinations, with views, reach, likes, comments, shares and saves where the platform supplies them. You need analytics:read for cached reads and analytics:write to refresh. Missing metrics stay absent or null; an unavailable metric is never an invented zero.

YouTube owner acceptance

Live YouTube analytics also require the channel owner’s explicit acceptance of the current Privacy Policy, version 2026-10-02. Existing channels can use Analytics → Review privacy. Keep the acceptance checkbox unchecked until the owner chooses it; do not infer acceptance from a previous connection, API access or OAuth approval.

POST /api/v1/accounts/{id}/analytics-consent
Authorization: Bearer cr_live_your_key
Content-Type: application/json

{"accepted":true,"privacy_policy_version":"2026-10-02"}

This endpoint requires accounts:write and returns the account with an analytics_consent receipt containing privacy_policy_version and accepted_at. Call it only after the channel owner accepts the current policy. The receipt belongs to that account’s current authorization and is not inherited by a reconnect. Until then, YouTube cached reads and refreshes report privacy_consent_required; metrics remain unavailable.

const filters = {
  profile_id: profile.id,
  from: '2026-10-01T00:00:00Z',
  to: '2026-10-31T23:59:59Z',
};

const { data: summary } = await castrook.analytics.summary(filters);
const { data: destinations, meta } = await castrook.analytics.posts({
  ...filters,
  platform: 'instagram',
  limit: 50,
});

Filters are profile_id, account_id, platform, from and to. Dates filter post creation time; the default is the last 30 days, with a maximum one-year range. Each destination contributes its latest snapshot once. The filter range does not choose the metric measurement window.

Inspect the measurement window

Read each row’s reporting_period: type: lifetime describes cumulative counters; type: date_range includes start_date and end_date. Pinterest reports a server-selected UTC range of at most 90 days, starting no earlier than the post’s creation. Its impressions map to views and its saves to saves. Other supported platforms use lifetime snapshots where available. Summary reporting_periods counts lifetime_destinations and date_range_destinations. Summary totals may combine measurement windows; don’t label those totals as lifetime counts or engagement earned in the filter range.

Inspect freshness and coverage

{
  "id": "snapshot_id",
  "post_id": "pst_example",
  "account_id": "acc_instagram",
  "platform": "instagram",
  "text": "A closer look.",
  "post_created_at": "2026-10-02T12:00:00Z",
  "status": "available",
  "metrics": { "views": 1280, "reach": 1048, "likes": 76, "comments": 4 },
  "unavailable_metrics": ["shares", "saves"],
  "fetched_at": "2026-10-02T12:30:00Z",
  "simulated": false,
  "reporting_period": { "type": "lifetime" }
}

Rows can be pending, available or unavailable. Read reason for permission, content or refresh failures. Summary totals uses null when no destination supplies a metric; coverage gives the available and total destination count for each metric. Use last_refreshed_at and row fetched_at to explain stale data.

Refresh a post

const { data: result } = await castrook.analytics.refresh(post.id);
// { post_id, refreshed, rows, cached }
// Read the destination statuses even when HTTP succeeds.

Refresh uses a five-minute cooldown. A recent snapshot can return cached: true; a concurrent refresh can return 409 analytics_refresh_in_progress. Scheduled refreshes are bounded. Cached GETs remain available after the monthly request allowance is exhausted; authentication, scope and per-minute rate limits still apply.

Platform access

• TikTok needs video.list for the connected creator’s video statistics. Photo and private-video statistics can be unavailable because TikTok’s Display API documents public videos.
• Instagram insights need instagram_business_manage_insights. Metric availability varies by media type and account.
• Facebook insights need read_insights and the relevant Page access.
• YouTube basic views, likes and comments use the existing YouTube Data permission. This release does not claim watch time, retention or full YouTube Analytics reports.
• Pinterest needs permitted Business-account Pin analytics. Trial Pins are Sandbox-only; unavailable metrics remain absent.
• LinkedIn performance requires granted Community Management read access for the connected profile or Page. Self-service sharing permission alone does not enable analytics.

Existing connections may need reconnection after new permission approval. Revoking or disconnecting an account removes its cached statistics. Expired YouTube data is omitted until refreshed under active authorization. Test mode uses clearly simulated metrics.

Current platform access · Full endpoint reference