Social Media Analytics API: Query Sources and Read Performance Metrics
A Social Media Analytics API should let a developer retrieve post performance without writing a separate parser for every platform. The endpoint described here returns normalized metrics for Twitter, YouTube, Pinterest, and LinkedIn Company Page posts through one schema, so impressions, likes, comments, shares, saves, clicks, views, and engagementRate can be handled consistently in application code.
One endpoint, one normalized schema
Posting content is only part of the workflow. A team also needs to know which posts generated impressions, which generated engagement, and which generated clicks. Native platform analytics do not use a shared vocabulary: one platform may call a metric public_metrics, another may return a statistics object, and another may split related signals across separate endpoints. Maintaining separate parsers, field names, and error handling for each platform makes cross-platform reporting brittle.
The Social Media Analytics API addresses that problem with one endpoint and one normalized schema for the supported platforms: Twitter, YouTube, Pinterest, and LinkedIn Company Page. A field that does not apply to a particular platform is returned as null rather than omitted, so client code can use the same field names for every platform and check for null where a metric is unavailable. The response also includes an aggregated object that sums applicable metrics across every platform a post was published to, which makes it possible to sort or report combined performance without performing the rollup in client code.
Each analytics call costs 1 credit, the same as a publish call, as stated in the source contract. That credit semantics is preserved here as a parity specification for future implementation.
Exact request contract and response schema
The endpoint is GET {{API_BASE_URL}}/v1/analytics. Requests use the x-access-key header with YOUR_API_KEY as the placeholder value in the examples. The same path supports four query shapes depending on the parameters supplied, so the implementation should branch on the combination of postId, platform, accountId, source, fromDate, toDate, sortBy, order, and limit rather than expecting four separate paths.
A successful response for a single post uses the fields success, post, source, postId, content, publishedAt, aggregated, platforms, platform, platformPostId, platformPostUrl, and metrics. Inside aggregated and inside each platform metrics object, the metric fields are impressions, likes, comments, shares, saves, clicks, views, and engagementRate. The example response shows impressions as 25, likes as 1, comments as 0, saves as 0, and shares, clicks, views, and engagementRate as null for that Twitter result, which illustrates the null-instead-of-missing rule. See the example analytics response in the code examples for the full preserved structure.
Before relying on a response in production code, check success first, then check whether the metrics you need are null for the platform in question. A null value is not a zero: it means the platform does not expose that signal in this schema, so aggregations and charts should treat null as unavailable rather than as no activity.
By post ID
Use the postId query mode when the post was published through the service and you want metrics for that post on every platform it was sent to. Pass postId with the internal post identifier and the x-access-key header. This is the right choice when your own database already stores the postId and you need the per-platform breakdown plus the aggregated totals in one call. See the query analytics by post ID example in the code examples.
By external platform ID
Use the external platform ID mode when you have a platform-native identifier, such as a tweet ID, a YouTube video ID, or a Pinterest pin ID, rather than an internal postId. Pass that identifier as postId together with platform and accountId. The service first looks for a matching post in your database; if no match is found, the platform and accountId parameters allow it to fetch directly from the platform. This mode is useful for importing performance for content that exists outside the publishing workflow, but it requires you to know both the platform and the accountId for the external ID. See the query analytics by external platform ID example in the code examples.
Paginated list
Use the paginated list mode when you want an overview of published posts rather than a single post. Omit postId and filter with platform, fromDate, toDate, sortBy, order, and limit. The source example filters to Twitter, limits results to a date range, sorts by likes in descending order, and returns ten items. This is the right choice for dashboards, weekly reporting, and finding top-performing posts, because the aggregated object lets you sort by combined likes or impressions across platforms without doing the rollup yourself. See the query a paginated analytics list example in the code examples.
Account posts pulled from the platform
Use the account pull mode when you need recent posts pulled directly from a platform account, including posts that were not published through the service. Set source=platform and pass accountId and platform, with limit to control how many posts are returned. The source example pulls Pinterest posts for an account. This mode suits account migration and content audits, where the goal is to inventory existing platform content before bringing it into a unified reporting workflow. See the pull account posts directly from the platform example in the code examples.
What metrics you actually get
Different platforms expose different signals, and the metric-by-platform table below makes that explicit instead of hiding it behind a generic engagement score. Twitter exposes impressions, likes, comments as replies, shares as retweets plus quotes, saves as bookmarks, and clicks as URL clicks, but not reach or views. YouTube exposes likes, comments, and views, but not impressions, reach, shares, saves, or clicks in this schema. Pinterest exposes impressions, likes as reactions, comments, saves, and clicks as outbound plus pin clicks, but not reach, shares, or views. LinkedIn Company Page exposes impressions, reach as unique impressions, likes, comments, shares, and clicks, but not saves or views.
The practical consequence is that a single dashboard metric may be comparable across some platforms and unavailable on others. Code should read the table as the contract for which fields to expect, treat null as unavailable, and use the aggregated object only for fields that are summed across the platforms a post was published to. If a report needs reach, for example, only LinkedIn Company Page supplies it in this schema; if it needs views, only YouTube supplies it. See the metric-by-platform table for the complete field map.
Try it without writing code
For a quick check without writing code, the no-code tools accept different inputs per platform. The Twitter tool takes a tweet URL or username, the YouTube tool takes a video URL or channel, the Pinterest tool takes a pin URL or board, and the LinkedIn tool shows metrics for posts on a Company Page. A multi-platform combined view brings the supported platforms together. These tools are described as hitting the same API under the hood, so the fields shown on the page correspond to the fields returned by the endpoint.
What's next
LinkedIn Company Page analytics are available through the LinkedIn Community Management API in the source contract, and every Company Page administered by a connected account is detected automatically and receives its own integration. Pass that integration's ID as accountId to fetch metrics for that Company Page. Analytics for posts on a personal LinkedIn profile are not covered by this scope and depend on a separate LinkedIn partner approval described as pending in the source, so personal-profile analytics should not be assumed to be available.
Instagram and TikTok analytics are likewise not yet covered in this schema and are described as next. The source states that the schema will not change as platforms are added and that fields will simply stop being null when a new platform supplies them, but until a platform is listed as supported, client code should not expect its metrics to be returned.
When evaluating the endpoint for implementation, start with the query mode that matches your data: postId if you store internal post IDs, external platform ID if you store native IDs, the paginated list if you need reporting across many posts, and source=platform if you need to audit an existing account. Then verify the metric table for the platforms you care about, confirm how null values should be handled in your charts and aggregations, and confirm the accountId for any LinkedIn Company Page integration before fetching metrics.
| Metric | YouTube | LinkedIn (Company Page) | ||
|---|---|---|---|---|
| impressions | yes | no | yes | yes |
| reach | no | no | no | yes (unique impressions) |
| likes | yes | yes | yes (reactions) | yes |
| comments | yes (replies) | yes | yes | yes |
| shares | yes (RT+quotes) | no | no | yes |
| saves | yes (bookmarks) | no | yes | no |
| clicks | yes (URL) | no | yes (outbound+pin) | yes |
| views | no | yes | no | no |
Availability as stated in source contract; unavailable fields return null.
curl "{{API_BASE_URL}}/v1/analytics?postId=69e0893109e2c65ae5957084" \
-H "x-access-key: YOUR_API_KEY"{
"success": true,
"post": {
"source": "postpeer",
"postId": "69e0893109e2c65ae5957084",
"content": "A short example update.",
"publishedAt": "2026-04-16T20:56:00.747Z",
"aggregated": {
"impressions": 25,
"likes": 1,
"comments": 0,
"shares": null,
"saves": 0,
"clicks": null,
"views": null,
"engagementRate": null
},
"platforms": [
{
"platform": "twitter",
"platformPostId": "2044882524506136582",
"platformPostUrl": "https://twitter.com/user/status/2044882524506136582",
"metrics": {
"impressions": 25,
"likes": 1,
"comments": 0,
"...": "..."
}
}
]
}
}curl "{{API_BASE_URL}}/v1/analytics?postId=2045080886845005934&platform=twitter&accountId=YOUR_ACCOUNT_ID" \
-H "x-access-key: YOUR_API_KEY"curl "{{API_BASE_URL}}/v1/analytics?platform=twitter&fromDate=2026-04-10&toDate=2026-04-17&sortBy=likes&order=desc&limit=10" \
-H "x-access-key: YOUR_API_KEY"curl "{{API_BASE_URL}}/v1/analytics?source=platform&accountId=YOUR_ACCOUNT_ID&platform=pinterest&limit=10" \
-H "x-access-key: YOUR_API_KEY"