Skip to content

Social Media Analytics API

A Social Media Analytics API gives developers one structured way to track post performance and engagement across connected social platforms.

Analytics request for one post
curl "{{API_BASE_URL}}/v1/analytics?postId=post_abc123" \
  -H "x-access-key: your-api-key"
Illustrative request
Example line 1

curl "{{API_BASE_URL}}/v1/analytics?postId=post_abc123" \

Illustrative request
Example line 2

-H "x-access-key: your-api-key"

Instead of building and maintaining separate analytics integrations for each network, you can request metrics in a single response and compare how the same content performed on Twitter/X, LinkedIn, YouTube, Instagram, Facebook, TikTok, and Pinterest. This page explains the evidenced request and response contract, how to read platform-specific metrics, and where the available evidence stops.

What a Social Media Analytics API does and who it is for

This kind of endpoint returns social performance figures to software on demand. A SaaS dashboard can present combined results for many networks, and a creator platform can highlight which items and channels drew the strongest response. The workflow is consistent: supply a post identifier, receive one structured record for each network where that item appeared, then compare those records directly.

A single endpoint suits products needing consistent cross-platform analytics, per-post comparison, and shared paging and ordering behaviour. Separate native connectors remain relevant when a network offers a capability absent from the unified response, or when its definitions need bespoke handling. Keep native measures intact alongside shared ones, since a retweet, a period of watch time, a save and a share do not mean the same thing.

Add social media to your product in three steps

Adding social capability follows three steps. First, get your API key by signing up; the key is sent in the x-access-key header on analytics requests. Second, integrate in minutes by connecting once, after which the same API can publish, schedule, analyze, manage comments, and handle messages. Third, support every major platform through that single connection, giving users access to major social platforms without building and maintaining each integration yourself.

In practice, complete the key step before any request, connect the accounts you intend to measure, then call the analytics endpoint with a postId. If a request returns no records, check the key, the postId, and whether the relevant accounts are connected before retrying.

Unified cross-platform metrics: field map and platform-specific metrics

The demonstrated request identifies a single item through the postId query parameter and yields one record per network. Every record contains postId, platform, platformPostId, accountId, metrics and collectedAt. Here platformPostId points to the item on its home network, accountId points to the linked account behind it, and collectedAt records when that network's figures were gathered. Because metrics differ by network, treat that object as network-specific rather than fixed.

Shared measures include impressions, likes, shares, clicks and engagement rate. Native examples include retweets and replies on Twitter/X, comments and shares on LinkedIn, views and watch time on YouTube, reach, saves and views on Instagram, and impressions, saves, clicks and closeups on Pinterest. The example titled Structured analytics response for one post shows one identifier producing a Twitter/X record and a LinkedIn record, each with its own native fields beside the shared ones.

Worked example: one postId, structured response

In the example, post_abc123 produces two records plus paging metadata: page 1, limit 25, total 2 and totalPages 1. In a product, start from the identifier stored at publish time, send the key in the x-access-key header, then group the data array by postId. Use platformPostId and accountId to trace each record to its native item and linked account, and use collectedAt to judge whether figures are current enough for display.

Check several failure modes before retrying. An empty data array may mean a wrong identifier or a disconnected account. A missing measure may simply not be supplied by that network. Differing collectedAt values mean the records are not one snapshot. A total above the number returned means more pages remain.

Filtering, sorting and pagination: evidenced behaviour and limits

Descriptions mention filtering by date interval, ordering by impressions, likes, engagement rate or date, and paging with page sizes up to 100. The concrete contract shown here evidences only postId, plus paging fields page, limit, total and totalPages. Names, requiredness and permitted values for date, platform, account and ordering parameters are not evidenced, so they should not be guessed.

Drive paging from the returned metadata: continue until total records have been gathered or totalPages has been reached, and keep limit at or below 100. Order only by measures actually present for the networks in the result set, since a measure available on one network may be absent on another.

Platform coverage

Twitter/X figures cover impressions, likes, retweets, replies, clicks and engagement. Instagram figures cover reach, likes, comments, shares, saves and views. Facebook figures cover Page post likes, comments, shares, clicks and any available video measures. LinkedIn figures cover Company Page impressions, reach, likes, comments, shares and clicks. TikTok figures cover video views, likes, comments and shares. YouTube figures cover views, likes, comments, watch time and engagement. Pinterest figures cover Pin impressions, saves, clicks, closeups and engagement. Which of these appear depends on the network and linked account, so interfaces should tolerate absent native measures.

Credits, freshness and failure matrix

One analytics call is charged at 1 credit, irrespective of how many posts or networks it returns, which favours fetching a paginated set in a single call over issuing separate calls per post. Timeliness depends on the network and measure, with some values arriving promptly and others delayed. collectedAt is the per-record freshness indicator.

Items created outside the API can still be measured on supported networks by fetching recent material from a linked account. Absent measures for a given network are normal variation, not failure. For incomplete-looking sets, verify the identifier, account linkage and paging state first.

Analytics response field map
FieldLocationMeaning
postIdQuery parameter and response recordIdentifier for the post whose analytics are requested
platformResponse recordNative platform for this record, for example twitter or linkedin
platformPostIdResponse recordIdentifier for the post on the native platform
accountIdResponse recordConnected account that published the post on that platform
metricsResponse recordPlatform-specific metrics object, such as impressions, likes, engagementRate, clicks
engagementRateInside metricsEngagement rate reported for that platform record
collectedAtResponse recordTimestamp when that platform result was collected
pagePagination objectCurrent page number
limitPagination objectPage size for this response
totalPagination objectTotal number of records matching the request
totalPagesPagination objectTotal number of pages available

Evidenced from the supplied request/response example; metrics contents vary by platform.

Platform coverage and native metrics
PlatformMetrics described in source
Twitter/XImpressions, likes, retweets, replies, clicks, engagement
InstagramReach, likes, comments, shares, saves, views
FacebookLikes, comments, shares, clicks, available video performance metrics
LinkedInImpressions, reach, likes, comments, shares, clicks
TikTokVideo views, likes, comments, shares
YouTubeVideo views, likes, comments, watch time, engagement
PinterestImpressions, saves, clicks, closeups, engagement

Metric availability varies by platform and connected account; not every metric is returned for every platform.

Failure and edge-case matrix
SituationWhat to checkHow to respond
Empty data arraypostId value and connected account statusVerify the postId and that accounts are linked before retrying
Metric missing for one platformWhether that platform returns the metric at allTreat as platform variation, not a request failure
Different collectedAt values across platformsFreshness of each recordDo not present records as a single snapshot
total larger than records returnedpage, limit and totalPagesRequest the next page until total records are collected
Post not published through the APIConnected account and platform sourceFor supported platforms, pull recent content from the connected account

Derived from source-stated freshness, metric variation, pagination and external-post behaviour.

Frequently asked questions

What is a social media analytics API?

It is an interface that returns performance figures for social posts in machine-readable form. A product can therefore show combined results in its own reporting screens, and a creator tool can rank posts by audience response, without wiring up a different connector for each network.

What social media metrics can I retrieve?

The set differs by network. Common examples are impressions, reach, views, likes, comments, shares, saves, clicks, watch time and engagement figures. Twitter/X records may include retweets and replies, YouTube records centre on views and watch time, and Instagram records may include reach, saves and views.

Can I get analytics for posts I didn't publish through the API?

For supported networks, yes. Recent items can be fetched from a linked account and treated as the source, so older material is measurable even if it was created elsewhere.

Can I sort social media analytics by performance?

Yes, where the underlying data supports it. Ordering can use measures such as impressions, likes, engagement or date, which helps dashboards and reports surface stronger performers first.

How fresh is the analytics data?

Timeliness varies. Figures come from the linked networks, so some values arrive promptly while others lag behind platform-side processing. Inspect collectedAt on each record to judge how recent that record is.

Do I need separate OAuth integrations for every platform?

A hosted connection flow removes that burden. Authorisation for supported networks is handled centrally, so a product does not need its own OAuth implementation for every network it wants to measure.

Structured analytics response for one post
{
  "success": true,
  "data": [
    {
      "postId": "post_abc123",
      "platform": "twitter",
      "platformPostId": "1234567890",
      "accountId": "acc_tw_123",
      "metrics": {
        "impressions": 4520,
        "likes": 87,
        "retweets": 23,
        "replies": 12,
        "engagementRate": 2.7,
        "clicks": 156
      },
      "collectedAt": "2026-03-31T12:00:00Z"
    },
    {
      "postId": "post_abc123",
      "platform": "linkedin",
      "platformPostId": "urn:li:share:7654321",
      "accountId": "acc_li_456",
      "metrics": {
        "impressions": 2100,
        "likes": 45,
        "comments": 8,
        "shares": 5,
        "engagementRate": 2.76,
        "clicks": 89
      },
      "collectedAt": "2026-03-31T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 2,
    "totalPages": 1
  }
}