# Analytics Views, likes, comments and audience figures for connected channels. Figures come from the results Soontra has already stored. If nothing is stored for the account and period asked for, the tool says so: ask Astrono in Soontra for that account’s analytics once, which loads them, then ask again. ### soontra_analytics_getAudience Audience splits for one account ({ account_id?, platform, period? }): age/gender, devices, and countries where available. Scope: `analytics` · Read-only | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `account_id` | string | no | 1 to 128 characters | | `platform` | "youtube" \| "instagram" | yes | | | `period` | "7d" \| "28d" \| "90d" | no | | Returns: For YouTube, `demographics`, `devices` and the top 10 countries in `geography`; for Instagram, an `audience` object; both with `period` and `account`. - YouTube and Instagram only. - `period` is `7d`, `28d` or `90d`; the default is `28d`. - The period is cut to the workspace plan's analytics window. - Served from cached data only: a window that is not cached returns an error asking you to open the Soontra analytics page first. - When several accounts could match, the answer is `selection_required` with up to 20 `choices`; pass one `account_id` and call again. ### soontra_analytics_getBestTimeToPost Historical publishing performance for one account ({ platform, days?, account_id? }). YouTube returns age-normalized day-of-week results; TikTok returns a UTC day-by-hour heatmap. Scope: `analytics` · Read-only | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `platform` | "youtube" \| "tiktok" | yes | | | `days` | integer | no | 7 to 365 | | `account_id` | string | no | 1 to 128 characters | Returns: For YouTube, `historical_publishing` by day of week; for TikTok, a `heatmap` by day and hour in UTC; both with `days`, `post_count` and `account`. - YouTube and TikTok only. - `days` is 7 to 365; the default is 90. - A shorter plan window shortens `days` and adds a `plan_note`. - Reads stored post data only; it never calls the platform. ### soontra_analytics_getBreakdown ONE deep analytics slice for a selected account. youtube/instagram: demographics | devices | geography | traffic_sources | playback_locations | content_types | retention | search_terms | subscriber_split. tiktok: duration | hashtags only. When several accounts are eligible, omit account_id and pass back the one from the returned selection_required choices. Cached data only. Scope: `analytics` · Read-only | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `platform` | "youtube" \| "instagram" \| "tiktok" | yes | | | `breakdown_type` | "demographics" \| "devices" \| "geography" \| "traffic_sources" \| "playback_locations" \| "content_types" \| "retention" \| "search_terms" \| "subscriber_split" \| "duration" \| "hashtags" | yes | | | `period` | "7d" \| "28d" \| "90d" | no | | | `account_id` | string | no | 1 to 128 characters | | `video_id` | string | no | 1 to 64 characters | Returns: The rows of one breakdown, with `platform`, `breakdown_type`, `period` and `account`. - YouTube takes every type except `duration` and `hashtags`. - Instagram takes `demographics`, `geography` and `content_types` only. - TikTok takes `duration` and `hashtags` only. - On YouTube, `retention`, `traffic_sources`, `search_terms` and `subscriber_split` need a `video_id`. - `period` is `7d`, `28d` or `90d`; the default is `28d`. - Served from cached data only: a window that is not cached returns an error asking you to open the Soontra analytics page first. ### soontra_analytics_getOverview Cross-platform headline analytics for one account per platform ({ account_id?, platforms?, period? }). When several accounts could match and account_id is omitted, returns selection_required with safe choices; account_id pins ONE platform, so re-call with platforms narrowed to that account's platform (one call per platform when several platforms are ambiguous). CACHED data only. Render not_connected honestly. Scope: `analytics` · Read-only | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `account_id` | string | no | 1 to 128 characters | | `platforms` | "youtube" \| "tiktok" \| "instagram"[] | no | 1 to 3 items | | `period` | "7d" \| "28d" \| "90d" | no | | Returns: An `overview` entry per platform (`connection`, `ok`, `headline`, `error`) with `platforms_queried`, `connected_count` and the `accounts` used. - Covers YouTube, TikTok and Instagram; all three when `platforms` is omitted. - `period` is `7d`, `28d` or `90d`. - An `account_id` pins one platform only, so narrow `platforms` to that platform. - Served from cached data only: a window that is not cached returns an error asking you to open the Soontra analytics page first. - When several accounts could match, the answer is `selection_required` with up to 20 `choices`; pass one `account_id` and call again. ### soontra_analytics_getPostAnalytics Per-platform performance of ONE published post ({ post_id }) from synced snapshots: views/likes/comments per target, permalink, and a state (not_posted | waiting_for_sync | ready | partial | not_connected). Use posts.list to find the post id. Scope: `analytics` · Read-only | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `post_id` | string (uuid) | yes | | Returns: A `state` (`not_posted`, `waiting_for_sync`, `ready`, `partial` or `not_connected`) and, per platform, the post's views, likes, comments and permalink. - Takes a Soontra `post_id`, as `posts.list` returns it. - Reads synced snapshots only; it never calls the platform. ### soontra_analytics_getTopContent Top-performing real content for one account ({ account_id?, platform, ... }). When more than one account is connected on that platform, omit account_id and pass back the one from the returned selection_required choices. Scope: `analytics` · Read-only | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `account_id` | string | no | 1 to 128 characters | | `platform` | "youtube" \| "instagram" | yes | | | `period` | "7d" \| "28d" \| "90d" | no | | | `limit` | integer | no | 1 to 50 | | `sort_by` | "views" \| "engagement" | no | | Returns: For YouTube, the top `videos`; for Instagram, the top `media` and a `summary`; both with `period` and `account`. - YouTube and Instagram only. - `limit` defaults to 10, maximum 50; Instagram allows at most 18. - `sort_by` is `views` (the default) or `engagement`. - `period` is `7d`, `28d` or `90d`; the default is `28d`. - The period is cut to the workspace plan's analytics window. - Served from cached data only: a window that is not cached returns an error asking you to open the Soontra analytics page first. ### soontra_analytics_query One custom analytics question ({ platform, account_id?, scope, metrics, window, granularity, breakdown?, filter?, sort?, limit? }): a post or the account over a date range, by day/week/month, by country or device, or the top posts by a metric. scope is { kind: 'account' } | { kind: 'posts', refs: [post links or ids] } | { kind: 'top', n, by }; window is { kind: 'lifetime' } | { kind: 'preset', preset: 'last_7d'|'last_28d'|'last_30d'|'last_90d'|'this_month'|'last_month' } | { kind: 'range', start, end } (YYYY-MM-DD). Metric keys (not every key answers every scope or window; a refusal says which do) - youtube: views, likes, comments, shares, watch_time_minutes, avg_view_duration_seconds, subscribers_gained, subscribers_lost, viewer_percentage, followers, posts_count, lifetime_views, title, published_at, duration_seconds, format; instagram: views, likes, comments, saves, shares, replies, total_interactions, reach, avg_watch_time_seconds, accounts_engaged, followers, posts_count, net_followers, title, published_at, duration_seconds, format; tiktok: views, likes, comments, shares, followers, posts_count, net_followers, lifetime_views, title, published_at, duration_seconds. YouTube: viewer_percentage needs breakdown age_gender; filter is country==US. Every answer carries provenance (source, asOf, the dates covered, notes). CACHED and stored data only: YouTube date ranges answer only when the question was already asked in Soontra, else reason window_not_cached. answerable false comes with a reason, a message and often closest (a question that can be answered); render it honestly. Scope: `analytics` · Read-only | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `account_id` | string | no | The account to read. Omit when the platform has one connected account. 1 to 128 characters | | `platform` | "youtube" \| "instagram" \| "tiktok" | yes | | | `scope` | object | yes | account: the whole account. posts: refs are post links, platform post ids or Soontra post ids. top: the n best posts ranked by the metric key 'by'. | | `scope.kind` | "account" | yes | | | `metrics` | string[] | yes | Metric keys from the platform's capability catalog. 1 to 8 items | | `window` | object | yes | lifetime; a preset; or a range with start and end as YYYY-MM-DD, both included. | | `window.kind` | "lifetime" | yes | | | `granularity` | "total" \| "day" \| "week" \| "month" | yes | total, or one row per day, week or month of a range. | | `breakdown` | string | no | One row per value of a breakdown from the capability catalog (country, device_type, traffic_source, age_gender...). 1 to 64 characters | | `filter` | string | no | YouTube only: country==US. 1 to 200 characters | | `sort` | object | no | | | `sort.metric` | string | yes | 1 to 64 characters | | `sort.direction` | "asc" \| "desc" | yes | | | `limit` | integer | no | 1 to 50 | Returns: An answer with `answerable`, the rows asked for and their provenance; when `answerable` is false, a `reason`, a `message` and often a `closest` question that can be answered. - YouTube, Instagram and TikTok. - 1 to 8 `metrics` a call; `limit` is 1 to 50. - A `posts` scope takes up to 250 `refs`; a `top` scope takes `n` from 1 to 50. - Range dates are `YYYY-MM-DD`, both included. - Served from cached and stored data only; it never calls the platform.