Analytics

Analytics endpoints need the analytics scope. Metrics are collected on a schedule in the background, so a post published a minute ago has not been measured yet.

All of these accept workspace_id to scope the answer and accountId to narrow it to one account. Ranges are given either as days or as an explicit from and to.

Overview

GET /v1/analytics/overview

curl "https://api.fopost.com/v1/analytics/overview?days=30" \
  -H "X-API-Key: $FOPOST_API_KEY"

Dashboard totals with period-over-period deltas, today's figures, and a per-account breakdown including follower history. This is the one endpoint to call if you only call one.

Time series

GET /v1/analytics/time-series

Daily buckets of engagement, followers, and post counts. Use days, or from and to for an explicit window. This is what you chart.

Top posts

GET /v1/analytics/top-posts

Posts ranked by engagement, or newest first with sort=recent. Takes limit, a range, accountId, and label.

It includes posts published natively on the network, not only ones that went out through FoPost, so the ranking reflects the account rather than the tool.

Demographics

GET /v1/analytics/demographics

Audience composition for the accounts whose networks report it. Networks differ in what they expose and in the minimum audience size they will report at all, so expect gaps rather than treating a missing breakdown as an error.

Posting streak

GET /v1/analytics/posting-streak

365 days of posting activity, one bucket per day. This is the contribution-graph view of whether you are actually shipping.

Label roll-up

GET /v1/analytics/labels

Aggregates performance by label, which is how you compare campaigns or clients when the posts are spread across accounts. Attach labels at post creation, then read them back here.

Posts table

GET /v1/analytics/posts-table

Posts with their per-account delivery breakdown, for building a table rather than a chart.

Collect on demand

POST /v1/analytics/collect

Forces a collection run for the active accounts instead of waiting for the next scheduled one. It is throttled per user: when you are over the limit, the 429 body carries retryAfter in seconds.

Use it after publishing something you want to measure now. Do not put it on a timer, since the scheduled collection is already doing that.

Next

Per-network metrics

GET /v1/accounts/{id}/insights?raw=true

curl "https://api.fopost.com/v1/accounts/$ACCOUNT_ID/insights?raw=true" \
  -H "X-API-Key: $FOPOST_API_KEY"

Every endpoint above answers in one vocabulary, so a number can be compared across networks. This one does the opposite: it answers in the network's own vocabulary, keyed by the metric names the platform itself uses.

That is where the numbers live that have no equivalent anywhere else. Facebook reports ad-break earnings for a monetised Page and splits impressions into paid and organic. Instagram reports how viewers left a story, split into taps forward, taps back, exits and swipes. TikTok reports its four video counts. YouTube reports a daily views series and, per video, an audience-retention curve. LinkedIn reports reactions split by type and page views split by surface. Google Business reports how people found the listing and which search terms surfaced it.

{
  "data": {
    "platform": "facebook",
    "account": {
      "fetched_at": "2026-09-20T02:00:00.000Z",
      "metrics": [
        { "key": "page_impressions", "label": "Page Impressions", "kind": "count", "value": 41800 },
        {
          "key": "page_daily_video_ad_break_earnings",
          "label": "Ad Break Earnings",
          "kind": "currency_usd",
          "value": 42.15
        }
      ]
    },
    "post": {
      "external_post_id": "1234567890_9876543210",
      "fetched_at": "2026-09-20T02:00:00.000Z",
      "metrics": [
        { "key": "post_impressions_paid", "label": "Paid Impressions", "kind": "count", "value": 1500 }
      ]
    }
  }
}

key is the platform's own metric name and never changes. label is ours and may be reworded, so read key if you are storing anything. kind tells you how to render the value: count, duration_ms, currency_usd, ratio, or series for a value that is an array of points rather than a number.

Both blocks come from the newest collected snapshot, not a live call to the network, so fetched_at is when the numbers were true. A network that reports nothing per post answers an empty post.metrics.

Reads are throttled the same way the rest of the API is, and the endpoint needs the analytics scope. Some networks gate their metrics behind an access grant we have requested and not yet received; those answer 503 with platform_metrics_unavailable rather than an empty set, so a pending grant never reads as a zero.