Social Media Analytics API
A Social Media Analytics API gives developers one structured way to track post performance and engagement across connected social platforms.
curl "{{API_BASE_URL}}/v1/analytics?postId=post_abc123" \
-H "x-access-key: your-api-key"curl "{{API_BASE_URL}}/v1/analytics?postId=post_abc123" \
-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.
| Field | Location | Meaning |
|---|---|---|
| postId | Query parameter and response record | Identifier for the post whose analytics are requested |
| platform | Response record | Native platform for this record, for example twitter or linkedin |
| platformPostId | Response record | Identifier for the post on the native platform |
| accountId | Response record | Connected account that published the post on that platform |
| metrics | Response record | Platform-specific metrics object, such as impressions, likes, engagementRate, clicks |
| engagementRate | Inside metrics | Engagement rate reported for that platform record |
| collectedAt | Response record | Timestamp when that platform result was collected |
| page | Pagination object | Current page number |
| limit | Pagination object | Page size for this response |
| total | Pagination object | Total number of records matching the request |
| totalPages | Pagination object | Total number of pages available |
Evidenced from the supplied request/response example; metrics contents vary by platform.
| Platform | Metrics described in source |
|---|---|
| Twitter/X | Impressions, likes, retweets, replies, clicks, engagement |
| Reach, likes, comments, shares, saves, views | |
| Likes, comments, shares, clicks, available video performance metrics | |
| Impressions, reach, likes, comments, shares, clicks | |
| TikTok | Video views, likes, comments, shares |
| YouTube | Video views, likes, comments, watch time, engagement |
| Impressions, saves, clicks, closeups, engagement |
Metric availability varies by platform and connected account; not every metric is returned for every platform.
| Situation | What to check | How to respond |
|---|---|---|
| Empty data array | postId value and connected account status | Verify the postId and that accounts are linked before retrying |
| Metric missing for one platform | Whether that platform returns the metric at all | Treat as platform variation, not a request failure |
| Different collectedAt values across platforms | Freshness of each record | Do not present records as a single snapshot |
| total larger than records returned | page, limit and totalPages | Request the next page until total records are collected |
| Post not published through the API | Connected account and platform source | For 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.
{
"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
}
}