Docs Reference

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

  • Scope analytics
  • Read-only

Audience splits for one account ({ account_id?, platform, period? }): age/gender, devices, and countries where available.

Parameters of soontra_analytics_getAudience
ParameterTypeDescription
account_idstring1 to 128 characters
platformrequired"youtube" | "instagram"
period"7d" | "28d" | "90d"

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

  • Scope analytics
  • Read-only

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.

Parameters of soontra_analytics_getBestTimeToPost
ParameterTypeDescription
platformrequired"youtube" | "tiktok"
daysinteger7 to 365
account_idstring1 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

  • Scope analytics
  • Read-only

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.

Parameters of soontra_analytics_getBreakdown
ParameterTypeDescription
platformrequired"youtube" | "instagram" | "tiktok"
breakdown_typerequired"demographics" | "devices" | "geography" | "traffic_sources" | "playback_locations" | "content_types" | "retention" | "search_terms" | "subscriber_split" | "duration" | "hashtags"
period"7d" | "28d" | "90d"
account_idstring1 to 128 characters
video_idstring1 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

  • Scope analytics
  • Read-only

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.

Parameters of soontra_analytics_getOverview
ParameterTypeDescription
account_idstring1 to 128 characters
platforms"youtube" | "tiktok" | "instagram"[]1 to 3 items
period"7d" | "28d" | "90d"

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

  • Scope analytics
  • Read-only

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.

Parameters of soontra_analytics_getPostAnalytics
ParameterTypeDescription
post_idrequiredstring (uuid)

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

  • Scope analytics
  • Read-only

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.

Parameters of soontra_analytics_getTopContent
ParameterTypeDescription
account_idstring1 to 128 characters
platformrequired"youtube" | "instagram"
period"7d" | "28d" | "90d"
limitinteger1 to 50
sort_by"views" | "engagement"

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

  • Scope analytics
  • Read-only

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.

Parameters of soontra_analytics_query
ParameterTypeDescription
account_idstringThe account to read. Omit when the platform has one connected account.1 to 128 characters
platformrequired"youtube" | "instagram" | "tiktok"
scoperequiredobjectaccount: 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.kindrequired"account"
metricsrequiredstring[]Metric keys from the platform's capability catalog.1 to 8 items
windowrequiredobjectlifetime; a preset; or a range with start and end as YYYY-MM-DD, both included.
window.kindrequired"lifetime"
granularityrequired"total" | "day" | "week" | "month"total, or one row per day, week or month of a range.
breakdownstringOne row per value of a breakdown from the capability catalog (country, device_type, traffic_source, age_gender...).1 to 64 characters
filterstringYouTube only: country==US.1 to 200 characters
sortobject
sort.metricrequiredstring1 to 64 characters
sort.directionrequired"asc" | "desc"
limitinteger1 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.