List what was published on each network in a date range, with per-post metrics
social_insights.posts.list
LeituraIdempotenteDesde 2026-11-01
Returns every post the organization's connected Instagram account, Facebook Page, TikTok account and LinkedIn Page published between from and to (YYYY-MM-DD, inclusive, up to 92 days, to not after today in the organization's time zone), newest first, read live from each network on every call (it can take several seconds; each network read counts against the external quota). platforms limits it to some of instagram, facebook, tiktok and linkedin. Each post has platform, external_id (the network's id), url, published_at (ms epoch), format (Instagram: feed, reel, story or carousel; TikTok: video), media_type, caption, thumbnail_url, planner_post_id (the Social Planner post that published it, when it went out from MB Suite) and metrics: reach, views, likes, comments, shares, saves, interactions (the sum of likes, comments, shares and saves the network gives) and engagement_rate (interactions over reach, or over views where there is no reach; engagement_base says which), each null when the network does not give it per post through MB Suite's connection (never an invented 0): Instagram gives all six; Facebook all but saves (views are media views, likes are all reactions); TikTok views, likes, comments and shares (lifetime, as of the read); LinkedIn only likes and comments. networks says, per network, ok with post_count, error with the reason (an expired connection, a missing permission, the network down: the other networks still return), not_connected, or withheld; truncated (and has_more) means the network returned its maximum of 100 posts for the range, so there may be more: narrow the range. YouTube videos are not included. 400 invalid_date, invalid_range, range_in_future or range_too_long for a bad range. Requires view access to Social Insights. With LinkedIn or TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their records are left out of the response (the permissions guide lists what each platform allows).
Instruções para agentes
A metric that comes null is not given by that network per post: say so instead of reporting a zero. If a network comes with error, name it and why.
Escopo
social_insights:read
Permissão
Ver o módulo
Tool do MCP
social_insights_posts_listNa superfície completa; na compacta, mb_execute_operation com id: "social_insights.posts.list".
Custo declarado: até 520 leituras e 0 escritas por chamada (contam na cota diária). Usa uma plataforma externa (meta): conta na cota de operações externas.
Parâmetros
fromstringqueryobrigatório
First day (YYYY-MM-DD, inclusive).
tostringqueryobrigatório
Last day (YYYY-MM-DD, inclusive; today at most). Up to 92 days.
platformsarray<enum>queryopcional
Only these networks: instagram, facebook, tiktok, linkedin (default: the four).
Valores: instagram, facebook, tiktok, linkedin
Resposta
rangeobject
networksarray<object>
dataarray<object>
has_moreboolean
True when a network reached its limit of 100 posts for the range (its truncated is true): there is no cursor (each network is read live), so narrow from/to to get the rest.
Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.
GET/v1/social-insights/posts/lookup
Get one published post with its metrics, by its link or its network id
social_insights.posts.get
LeituraIdempotenteDesde 2026-11-01
Finds one post the organization published on Instagram, Facebook, TikTok or LinkedIn and returns it with its current metrics, read live from the network (each call counts against the external quota). Send url (the post's link on the network; the network comes from the domain) or external_id with platform (instagram, facebook, tiktok or linkedin); a Facebook video or reel is also found by the id of the video (the one in its /videos/, /reel/ or watch?v= link, which is what the Social Planner keeps for a video). It reads only a few days around the post, with the date it can know: published_on (YYYY-MM-DD) when sent; else the date MB Suite already knows (the publish job that posted it from the Social Planner, or the copy the Planner's published feed synced); else the date the network gives first: an Instagram link by its code, looking through what the account published from the newest post back in 60-day steps (listings without metrics, one call per step, each step seeing the newest 100 posts of its 60 days) until it finds the code, reaches 2 years back or finds 3 steps in a row with no posts (about 6 months); and an Instagram or Facebook id with one call (on Facebook one more for the Page token, and one more when an id without the Page in front is tried as the Page's post; an Instagram id counts only when the post belongs to the connected account). When the date cannot be known (TikTok, LinkedIn, a post the network did not date) it reads the last 90 days: Instagram and Facebook in 30-day windows, newest first, stopping when it finds the post; TikTok and LinkedIn in one read (their connections list from the newest post back on every read, LinkedIn only its last 100 posts); each read is one external quota unit. The search stops at about 40 seconds: no new read starts after that. Returns post (the same shape as social_insights.posts.list: platform, external_id, url, published_at, format, media_type, caption, thumbnail_url, planner_post_id and metrics) and searched (the dates it read). metrics: reach, views, likes, comments, shares, saves, interactions (the sum of likes, comments, shares and saves the network gives) and engagement_rate (interactions over reach, or over views where there is no reach; engagement_base says which), each null when the network does not give it per post through MB Suite's connection (never an invented 0): Instagram gives all six; Facebook all but saves (views are media views, likes are all reactions); TikTok views, likes, comments and shares (lifetime, as of the read); LinkedIn only likes and comments. With include_insights=true it also returns what the network gives for that post beyond those metrics, read live with one more call: on Instagram by format (feed and carousel: reach, views, likes, comments, shares, saved, total_interactions, profile_visits, profile_activity, follows; reel: reach, views, likes, comments, shares, saved, total_interactions, ig_reels_avg_watch_time, ig_reels_video_view_total_time; story: reach, views, replies, shares, total_interactions, follows, profile_visits, navigation) and on Facebook post_total_media_view_unique, post_media_view, post_reactions_by_type_total, post_activity_by_action_type, post_clicks, post_clicks_by_type, post_video_views, post_video_avg_time_watched. insights is a flat map keyed by the network's own metric ids, kept as they are, with the network's own values as given; a breakdown comes as one key per type (post_reactions_by_type_total.like, post_activity_by_action_type.share; a type with no activity is left out). On a Facebook reel the network may give post_total_media_view_unique as 0 while post_media_view has views: that is reach it did not measure (post.metrics.reach is then null), not zero people. insights_unavailable lists the requested metrics the network did not give for that post (when the network rejects the batch, each metric is asked alone); insights_error says why none came (an expired connection, a missing permission, the network down, a demo organization), and the post still returns with its metrics. TikTok and LinkedIn give nothing beyond the post's metrics through MB Suite's connection: insights is null. Each call to Meta counts against the external quota: usually 1 more on Instagram and 2 more on Facebook (the Page token), up to 11 when the network rejects the batch. Without include_insights none of these three fields come. 404 social_post_not_found when it is not among what the connected account published in what was searched: details.searched_from and searched_to say how far it looked, and details.time_limit_reached is true when the time limit cut the search; when that look-up does not find an Instagram link's code it is 404 without reading any metrics, with details.searched_from as far back as it looked (it stops early after about 6 months with no posts, and an account with more than 100 posts in 60 days can hide its older ones from it); send published_on to look at another day. 409 integration_not_connected when that network is not connected; 400 post_reference_required, url_not_recognized, platform_required or platform_mismatch for a bad reference. A LinkedIn link to an activity (urn:li:activity) may not match its post id: prefer the post's own link. Requires view access to Social Insights. With LinkedIn or TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted (the permissions guide lists what each platform allows).
Instruções para agentes
A metric that comes null is not given by that network per post: say so instead of reporting a zero. A metric in insights_unavailable was not given for that post; with insights_error, name the reason instead of reporting zeros.
Escopo
social_insights:read
Permissão
Ver o módulo
Tool do MCP
social_insights_posts_getNa superfície completa; na compacta, mb_execute_operation com id: "social_insights.posts.get".
Custo declarado: até 140 leituras e 0 escritas por chamada (contam na cota diária). Usa uma plataforma externa (meta): conta na cota de operações externas.
Parâmetros
urlstringqueryopcional
The post's link on the network (instagram.com, facebook.com, tiktok.com, linkedin.com). Send url, or external_id with platform.
external_idstringqueryopcional
The post's id on the network (with platform), as social_insights.posts.list or a Planner publish job gives it.
platformenumqueryopcional
The network of external_id: instagram, facebook, tiktok or linkedin.
Valores: instagram, facebook, tiktok, linkedin
published_onstringqueryopcional
The day it went out (YYYY-MM-DD), if known: it narrows the search.
include_insightsbooleanqueryopcional
Also everything the network gives about the post (Instagram by format, Facebook the page post's insights): one more call to the network. Default false.
Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.
