IVYXSTUDIO · IVY AGENT

Social collect

ivy.agent.social-collect · v0.1.0

ivyx

Reads a brand's social accounts and answers the collector's snapshot: Instagram (insights and media), Facebook (Page insights), LinkedIn (company statistics and posts), X (the account and its posts) and YouTube (the channel, its analytics and its videos), each behind an if on whether the brand has that platform, then the snapshot builder, which computes each account's headline median and every post's lift. IVYX Social's intake takes the output as social-snapshot and every analytics card draws from it. Reads only.

Steps

In the order the agent's file lists them, each with where its inputs come from and the values the file fixes. A branch or a loop is a step too.

01
Which platforms does the brand have?
ivy.node.social-plan
Reads an IVYX Social collect or inbox agent's input (a connection and an id per platform) and says which platforms are there, so the agent's if-branches run only those steps.
takes
firm from the agent's input
client from the agent's input
days from the agent's input
ig_connection from the agent's input
ig_user_id from the agent's input
fb_connection from the agent's input
fb_page_id from the agent's input
li_connection from the agent's input
li_organization_id from the agent's input
li_handle from the agent's input
x_connection from the agent's input
x_handle from the agent's input
yt_connection from the agent's input
Ivy Node
02
Instagram?
Lets what follows run only when has_instagram of step 1 is true.
Branch
03
Instagram: insights per day
ivy.node.ig-insights
Reads an Instagram professional account's daily figures through the Graph API with a Meta connection: reach and new follows as a day series, and views, total interactions, accounts engaged and profile link taps as one total per day, for the days asked for; the account's followers, following and media counts as today's instant values.
Runs only on the then branch of step 2.
takes
connection from the agent's input, ig_connection
ig_user_id from the agent's input
days from the agent's input
Ivy Node
04
Instagram: posts with their insights
ivy.node.ig-media
Reads an Instagram professional account's recent media (posts, reels, carousels) through the Graph API with a Meta connection, and each one's lifetime insights (reach, views, likes, comments, shares, saves, total interactions, a reel's average watch time).
Runs only on the then branch of step 2.
takes
connection from the agent's input, ig_connection
ig_user_id from the agent's input
Ivy Node
05
Facebook?
Lets what follows run only when has_facebook of step 1 is true.
Branch
06
Facebook: Page insights
ivy.node.fb-page-insights
Reads a Facebook Page's daily figures through the Graph API with a Meta connection: impressions and new fans per day, and the Page's fan and follower counts as today's instant values.
Runs only on the then branch of step 5.
takes
connection from the agent's input, fb_connection
page_id from the agent's input, fb_page_id
days from the agent's input
Ivy Node
07
LinkedIn?
Lets what follows run only when has_linkedin of step 1 is true.
Branch
08
LinkedIn: page statistics
ivy.node.li-org-stats
Reads a LinkedIn company page's daily figures through the Community Management API with a LinkedIn connection: new followers (organic and sponsored), share statistics (impressions, unique impressions, clicks, reactions, comments, reposts, the engagement rate), page views and unique visitors by page, and the follower total as today's instant value.
Runs only on the then branch of step 7.
takes
connection from the agent's input, li_connection
organization_id from the agent's input, li_organization_id
handle from the agent's input, li_handle
days from the agent's input
Ivy Node
09
LinkedIn: posts
ivy.node.li-posts
Reads a LinkedIn company page's posts through the Community Management API with a LinkedIn connection, and each one's lifetime share statistics (impressions, clicks, reactions, comments, reposts, engagement).
Runs only on the then branch of step 7.
takes
connection from the agent's input, li_connection
organization_id from the agent's input, li_organization_id
Ivy Node
10
X?
Lets what follows run only when has_x of step 1 is true.
Branch
11
X: the account's counts
ivy.node.x-user
Reads an X account's public counts (followers, following, posts, listed) through the X API v2 with an X connection, as today's instant values in the collector's daily block; the signed-in account when no handle is given.
Runs only on the then branch of step 10.
takes
connection from the agent's input, x_connection
handle from the agent's input, x_handle
Ivy Node
12
X: posts with their metrics
ivy.node.x-posts
Reads an X account's recent posts through the X API v2 with an X connection, with the public metrics of each and, for the account's own posts under thirty days old, the private ones (impressions, engagements, profile and link clicks), as the collector's posts block with post_key x:<id>.
Runs only on the then branch of step 10.
takes
connection from the agent's input, x_connection
user_id from step 11
Ivy Node
13
YouTube?
Lets what follows run only when has_youtube of step 1 is true.
Branch
14
YouTube: the channel
ivy.node.yt-channel
Reads the signed-in Google account's YouTube channel through the Data API with a Google connection: its id, title, uploads playlist, and subscribers, views and videos as today's instant values in the collector's daily block.
Runs only on the then branch of step 13.
takes
connection from the agent's input, yt_connection
Ivy Node
15
YouTube: analytics per day
ivy.node.yt-analytics
Reads the channel's daily analytics through the YouTube Analytics API with a Google connection: views, minutes watched, average view duration and percentage, subscribers gained and lost, likes, comments and shares per day, as the collector's daily block; and views by traffic source over the range as the traffic_source breakdown the YouTube tab draws.
Runs only on the then branch of step 13.
takes
connection from the agent's input, yt_connection
days from the agent's input
Ivy Node
16
YouTube: videos
ivy.node.yt-videos
Reads the channel's uploads through the Data API with a Google connection: each video's title, publish time, thumbnail, duration, and lifetime views, likes and comments, as the collector's posts block with post_key youtube:<video id>; and, for the newest videos, their daily views through the Analytics API as the per-video day series the YouTube tab draws (post_daily).
Runs only on the then branch of step 13.
takes
connection from the agent's input, yt_connection
uploads from step 14
Ivy Node
17
The collector's snapshot
ivy.node.social-snapshot-build
Assembles the collector's schema v1 document (IVYX Social's social-snapshot) from what the platform nodes answered: the accounts with their daily rows and posts, each account's headline metric and its median over the last 365 days, each post's lift against it (10 posts at least), the per-platform spans, the metric legend, the gaps of accounts that could not be read.
Runs only on the else branch of step 13.
takes
client from the agent's input
account_a from step 3
account_b from step 4
account_c from step 6
account_d from step 8
account_e from step 9
account_f from step 11
account_g from step 12
account_h from step 14
account_h.daily from step 15, daily
account_h.breakdowns from step 15, breakdowns
account_h.posts from step 16, posts
account_h.post_daily from step 16, post_daily
account_h.headline_metric from step 16, headline_metric
returns
schema_version, generated_at, settings, metrics, platforms, accounts, breakdowns, flags, gaps, annotations, warnings, client, count
Ivy Node

Nodes it brings

Adding this agent in IVYX Studio adds these nodes with it. A node your workspace already has is kept as it is, even at another version.

What it touches

Collected from what each of its nodes declares, plus the model call when a step is a model turn. A declaration is the author's statement, and it is what policy rules select on.

Network

Inputs

Field	Type	Description
firm	string	The firm's slug in IVYX Social; the destination routes the delivery to /api/firms/<firm>/intake.
clientrequired	string	The brand's name, as IVYX Social knows it; the destination hands it on as the delivery's client.
days	integer	How many days back to read; 7 when omitted (a first collection asks for 365).
ig_connection	Not declared	The platform's connection, as the stored secret connection.<id>.
ig_user_id	string	The Instagram professional account's id.
fb_connection	Not declared	The platform's connection, as the stored secret connection.<id>.
fb_page_id	string	The Facebook Page's id; the first managed Page when omitted.
li_connection	Not declared	The platform's connection, as the stored secret connection.<id>.
li_organization_id	string	The LinkedIn company page's id or URN.
li_handle	string	Its vanity name.
x_connection	Not declared	The platform's connection, as the stored secret connection.<id>.
x_handle	string	The X account's handle.
yt_connection	Not declared	The platform's connection, as the stored secret connection.<id>.

Outputs

Field	Type	Description
schema_versionrequired	integer	1
generated_at	string	Not declared
settings	object	Not declared
metrics	object	Not declared
platforms	object	Not declared
accountsrequired	array	The accounts with their daily rows and posts.
breakdowns	object	Not declared
flags	array	Not declared
gaps	array	Not declared
annotations	array	Not declared
warnings	array	Not declared
client	string	Not declared
count	integer	Not declared

Tests

2 of 2 test cases passed on Oct 25, 2026, in the publisher's own environment, before this version was published. The registry keeps that record; it does not run the cases again.

Requires: python:3.9, tools/connectors-standin.py on 127.0.0.1:18911, its connections stored as the secrets connection.standin-<platform>

five-platforms
A brand on all five platforms, read through the stand-in apps, is a schema v1 snapshot with an account per platform and no gap.
given
firm ivyx
client IVYX
days 2
ig_connection {"$secret":"connection.standin-meta"}
ig_user_id 17841400001
fb_connection {"$secret":"connection.standin-meta"}
li_connection {"$secret":"connection.standin-linkedin"}
li_organization_id 123
li_handle ivyx
x_connection {"$secret":"connection.standin-x"}
x_handle ivyxai
yt_connection {"$secret":"connection.standin-google"}
expects
schema_version equals 1
client equals IVYX
count equals 5
gaps equals []
no-platform
A brand with no connection is a snapshot with no account and a warning that says why.
given
firm ivyx
client IVYX
expects
schema_version equals 1
count equals 0
warnings.0 equals No platform answered: the brand has no connection, or every read failed.