Social Performance

GET /api/v1/social/performance — engagement data for published posts, so agents can learn what performs before drafting.

Updated 11d ago

In short

Engagement snapshots (views/likes/comments/shares/saves per platform) are captured automatically ~1h, 24h, 72h and 7d after each post publishes. This route returns published posts with their first and latest snapshots — read it before drafting to see which content, platforms and timing perform.

How metrics are collected

After a post publishes, an hourly collector reads live engagement from each platform through Chirio on a decaying schedule — roughly 1h, 24h, 72h, and 7d after publish. The ~1h snapshot captures early velocity; the ~7d snapshot the settled totals. Collection then stops (engagement plateaus within a week). A metric is null when the platform doesn't expose it or the connected account's token can't read it — never zero. Notable platform limits:

Platform	Available	Notes
Instagram	views, reach, likes, comments, saves, shares	views/reach/saves/shares need a token with the insights permission — accounts connected before it was requested must be reconnected
Threads	views, likes, replies, reposts, quotes, shares	All metrics need the insights permission; older connections must be reconnected
X	impressions, likes, replies, retweets, bookmarks, quotes	Reading metrics requires a paid X API tier; on the free tier every metric fails
LinkedIn	likes, comments	No view counts on this API surface
Reddit	score (as likes), comments, upvote ratio	Always available
Orbit	—	No readable metrics surface; targets report null metrics

Get performance

GET /api/v1/social/performance?days=&limit=&offset=
Authorization: Bearer av_live_…

Required scope: social:write

Query parameters

Param	Description
days	Look-back window in days (default 30, max 90)
limit	Max posts to return (default 50, max 100)
offset	Pagination offset

Example response

first is the earliest snapshot (early velocity — the strongest predictor of final reach); latest the most recent (settled totals). Both are null for a post published less than ~1h ago. The full snapshot series for one post is returned by Get post as metrics.

Errors

HTTP	Code	When
400	VALIDATION_ERROR	Non-numeric days/limit/offset
401	UNAUTHORIZED	Missing or invalid token
403	FORBIDDEN	Token lacks social:write

Social Posts

Website Mockup Video

How metrics are collected

A metric is null when the platform doesn't expose it or the connected account's token can't read it — never zero. Notable platform limits:

Platform	Available	Notes
Instagram	views, reach, likes, comments, saves, shares	views/reach/saves/shares need a token with the insights permission — accounts connected before it was requested must be reconnected
Threads	views, likes, replies, reposts, quotes, shares	All metrics need the insights permission; older connections must be reconnected
X	impressions, likes, replies, retweets, bookmarks, quotes	Reading metrics requires a paid X API tier; on the free tier every metric fails
LinkedIn	likes, comments	No view counts on this API surface
Reddit	score (as likes), comments, upvote ratio	Always available
Orbit	—	No readable metrics surface; targets report null metrics

Get performance

GET /api/v1/social/performance?days=&limit=&offset= Authorization: Bearer av_live_…

Required scope: social:write

Query parameters

Param	Description
days	Look-back window in days (default 30, max 90)
limit	Max posts to return (default 50, max 100)
offset	Pagination offset

Example response

{
  "posts": [
    {
      "postId": "d5c9…",
      "content": "Launch day! …",
      "platformOverrides": { "threads": "Shorter launch caption…" },
      "publishedAt": "2026-08-03T09:00:12Z",
      "targets": [
        {
          "platform": "instagram",
          "accountId": "acc_…",
          "url": "https://www.instagram.com/p/…",
          "first": {
            "stage": 0,
            "views": 412, "likes": 38, "comments": 4, "shares": 2, "saves": 6,
            "extra": { "reach": 390 },
            "capturedAt": "2026-08-03T10:00:41Z"
          },
          "latest": {
            "stage": 3,
            "views": 5210, "likes": 301, "comments": 27, "shares": 19, "saves": 44,
            "extra": { "reach": 4788 },
            "capturedAt": "2026-08-10T09:30:08Z"
          }
        }
      ]
    }
  ]
}

HTTP

Code

When

400

VALIDATION_ERROR

Non-numeric days/limit/offset

401

UNAUTHORIZED

Missing or invalid token

403

FORBIDDEN

Token lacks social:write

Social Performance

Social Performance

How metrics are collected

Get performance

Query parameters

Example response

Errors

Related

How metrics are collected

Get performance

Query parameters

Example response

Errors

Related