Skip to content

Get Analytics API

The Get Analytics API retrieves performance metrics for your social media posts across all connected platforms. Use it for a single post by passing postId, or omit postId to return a paginated list of published posts with analytics. It accepts both internal post IDs and external platform post IDs that are auto-resolved, and each call costs 1 credit.

Endpoint and cost

Call GET {{API_BASE_URL}}/v1/analytics to retrieve analytics. Supplying postId narrows the call to one item; leaving it out yields a paginated collection of published items with their analytics. Each call costs 1 credit. Review the request examples titled Single post by internal post ID request, External platform post ID lookup request, Paginated analytics list request, and Account posts fetched directly from platform request before selecting parameters.

Query parameters

Every query parameter is optional in the schema, yet certain combinations impose extra requirements. postId is a string that may be an internal post ID or an external platform post ID. platform filters by twitter, instagram, youtube, tiktok, pinterest, linkedin, facebook, threads, or bluesky, and is required for external ID lookups. accountId is an integration ID required for external ID lookups and for source=platform. source distinguishes stored posts published through the system from posts fetched directly from the connected platform account; omit source to include all sources. fromDate is an inclusive start date in YYYY-MM-DD format and defaults to 90 days ago. toDate is an inclusive end date in YYYY-MM-DD format and defaults to today, with a maximum range of 366 days. sortBy may be date, likes, comments, impressions, views, shares, saves, clicks, or engagement. order may be asc or desc. limit is an integer page size from 1 to 100, and page is an integer page number. See the Query parameters input contract table for the full contract.

Four usage modes

Four distinct retrieval patterns are supported. Pattern one uses an internal postId and returns combined metrics for every destination that item reached. Pattern two uses a native identifier from the destination service, such as a tweet ID, YouTube video ID, or Pinterest pin ID; stored items are searched first, and a direct platform fetch is attempted when platform and accountId accompany the identifier, producing source platform and postId null. Pattern three leaves postId empty and returns the full published collection, with optional platform filtering, date bounds, and ordering. Pattern four combines source=platform with accountId to pull recent items straight from the destination service, even when they never passed through the source system, again yielding source platform and postId null. Platforms available under source=platform are Twitter, YouTube, Pinterest, LinkedIn (Company Pages), TikTok, Facebook (Pages), Instagram (Business), and Threads.

Mode 1: Single post by internal post ID

Pattern one is the simplest: supply an internal postId and inspect the combined figures for each destination. The response example titled Single post analytics response example illustrates success true, a post object carrying source, postId, content, publishedAt, aggregated figures including impressions, and a platforms array whose entries hold platform, platformPostId, platformPostUrl, and metrics. A null inside metrics signals that the destination does not supply that figure, not that the value is zero.

Mode 2: External platform post ID auto-resolution

Pattern two starts with a native identifier from the destination service. Stored items are searched by that identifier first. When no stored match exists, adding platform and accountId triggers a direct fetch from the destination service. In that direct-fetch outcome, source equals platform, postId equals null, and content plus publishedAt can also be null, as shown in the External platform post ID lookup response example. Include platform and accountId whenever a native identifier might need the direct-fetch fallback.

Mode 3: Paginated list without postId

Pattern three omits postId entirely, returning analytics across the published collection. Add platform, fromDate, toDate, sortBy, order, limit, and page to narrow, order, and page through results. List responses carry success true, total, page, limit, and a posts array, illustrated in the Paginated analytics list response example. Choosing sortBy likes with order desc surfaces the strongest performers first; compare page and limit against total while iterating.

Mode 4: Account posts from the platform directly

Pattern four sets source=platform alongside accountId, pulling recent items directly from the destination service, including items never published through the source system. Every entry in that mode carries source platform and postId null, as shown in the Account posts fetched directly from platform response example. For LinkedIn, the LinkedIn Company Page analytics response example shows the expected shape, and accountId must identify the Company Page integration rather than a personal profile integration. Connecting LinkedIn creates one integration for the personal profile plus one per administered Company Page, so pick the Company Page integration identifier here.

ID resolution order

When postId is supplied, resolution proceeds in a fixed sequence. First, the value is tried as an internal post ID. Second, stored items are searched where platformPostId matches, which resolves a native identifier automatically. Third, when platform and accountId are also present, the destination service is queried directly. A native identifier without platform and accountId will not resolve if no stored match exists.

Metrics by platform

Every destination shares one unified metric schema, with null marking figures a destination does not supply. The Metrics by platform matrix details support for impressions, reach, likes, comments, shares, saves, clicks, views, engagementRate, avgWatchTime, and totalWatchTime across Twitter, YouTube, Pinterest, LinkedIn Company Pages, TikTok, Facebook Pages, Instagram Business, and Threads. avgWatchTime and totalWatchTime apply only to Instagram Reels and are measured in seconds: the former averages watch time per view, the latter totals watch time including replays and may be null because Meta flags it as in development. LinkedIn Company Page posts are supported through LinkedIn's Community Management API, while personal profile posts return null metrics until a separate LinkedIn partner approval lands. TikTok supplies views, likes, comments, and shares through the Display API under the video.list scope, with no additional TikTok audit needed on the caller side, but impressions, reach, saves, clicks, and engagementRate remain null. Facebook Pages supply likes, comments, shares, and views on video and Reel posts, with views read from the video object's views field under pages_read_engagement; impressions, reach, and click-through data require the separate read_insights scope, which has not been requested, and personal Facebook profiles are unsupported. Instagram supplies reach, likes, comments, shares, and saves for Business and Creator accounts through the instagram_business_manage_insights scope, so reconnecting the account is needed to pick up insights, and personal accounts cannot connect through the Graph API.

Status codes and error response

Expect 200 for success, 400 for invalid query parameters such as a date range exceeding 366 days, 402 for not enough credits, and 404 for post not found. Failures use success false plus a message string, illustrated in the Error response example for date range exceeding 366 days. On a 400, check fromDate and toDate format and range, limit bounds, and required combinations for external ID and source=platform calls before retrying. On a 402, check available credits. On a 404, verify postId, platformPostId resolution, and whether platform and accountId are needed for a direct fetch.

Query parameters input contract
ParameterTypeRequiredDescription
postIdstringNoInternal post ID or external platform post ID (auto-resolved). When omitted, returns a paginated list of all published posts with analytics.
platformstringNoFilter by platform: twitter, instagram, youtube, tiktok, pinterest, linkedin, facebook, threads, bluesky. Required for external ID lookups.
accountIdstringNoIntegration ID. Required for external ID lookups and source=platform.
sourcestringNo"postpeer" (posts published via the system, stored in DB) or "platform" (fetched directly from the connected platform account). Omit to include all sources.
fromDatestringNoInclusive start date (YYYY-MM-DD). Defaults to 90 days ago.
toDatestringNoInclusive end date (YYYY-MM-DD). Defaults to today. Max range: 366 days.
sortBystringNoSort by: date, likes, comments, impressions, views, shares, saves, clicks, engagement.
orderstringNoasc or desc.
limitintegerNoPage size (1-100).
pageintegerNoPage number.

All parameters are listed as not required in the source schema; platform and accountId are conditionally required for external ID lookups and source=platform as described.

Metrics by platform
MetricTwitterYouTubePinterestLinkedIn (Company Page)TikTokFacebook (Page)Instagram (Business)Threads
impressionsyes—yesyes————
reach———yes (unique impressions)——yes—
likesyesyesyes (reactions)yesyesyesyesyes
commentsyes (replies)yesyesyesyesyesyesyes (replies)
sharesyes (RT + quotes)——yesyesyesyesyes (reposts)
savesyes (bookmarks)—yes———yes—
clicksyes (url clicks)—yes (outbound + pin)yes————
views—yes——yesyes (video)—yes
engagementRate———yes————
avgWatchTime——————yes (Reels)—
totalWatchTime——————yes (Reels)—

Fields return null when the platform does not support that metric.

Status codes
CodeMeaning
200Success
400Invalid query parameters (e.g. date range exceeds 366 days)
402Not enough credits
404Post not found

Status contract preserved from source.

Frequently asked questions

When should I pass postId and when should I omit it?

Pass postId for a single post. Omit postId to return a paginated list of published posts with analytics, optionally filtered by platform, source, fromDate, toDate, sortBy, order, limit, and page.

What is required for an external platform post ID lookup?

Provide platform and accountId with the external postId. The lookup first searches stored posts by platformPostId, and if not found, fetches directly from the platform API when platform and accountId are provided. In that direct case source is platform and postId is null.

How do I fetch recent account posts directly from a platform?

Set source=platform with accountId, and platform where required for the account. Supported platforms for source=platform are Twitter, YouTube, Pinterest, LinkedIn (Company Pages), TikTok, Facebook (Pages), Instagram (Business), and Threads. Each result has source platform and postId null.

Why are some metric fields null?

All metrics use a unified schema and fields return null when the platform does not support that metric. For example, engagementRate is supported for LinkedIn Company Pages in the matrix, while impressions is supported for Twitter, Pinterest, and LinkedIn Company Pages.

Which status codes should I handle?

Use 200 for success, 400 for invalid query parameters such as a date range exceeding 366 days, 402 for not enough credits, and 404 for post not found. The error response uses success false and a message field.

Single post by internal post ID request
GET {{API_BASE_URL}}/v1/analytics

curl "{{API_BASE_URL}}/v1/analytics?postId=69e0893109e2c65ae5957084" \
  -H "x-access-key: YOUR_API_KEY"
External platform post ID lookup request
curl "{{API_BASE_URL}}/v1/analytics?postId=2045080886845005934&platform=twitter&accountId=69da6882322e75b602ad2916" \
  -H "x-access-key: YOUR_API_KEY"
External platform post ID lookup response example
{
	"success": true,
	"post": {
		"source": "platform",
		"postId": null,
		"content": null,
		"publishedAt": null,
		"aggregated": {
			"impressions": 22,
			"reach": null,
			"likes": 1,
			"comments": 1,
			"shares": null,
			"saves": 0,
			"clicks": null,
			"views": null,
			"engagementRate": null
		},
		"platforms": [
			{
				"platform": "twitter",
				"platformPostId": "2045080886845005934",
				"platformPostUrl": null,
				"metrics": {
					"impressions": 22,
					"reach": null,
					"likes": 1,
					"comments": 1,
					"shares": null,
					"saves": 0,
					"clicks": null,
					"views": null,
					"engagementRate": null
				}
			}
		]
	}
}
Paginated analytics list request
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"
Account posts fetched directly from platform request
curl "{{API_BASE_URL}}/v1/analytics?source=platform&accountId=69e2275c1d7a0d479237fa67&platform=pinterest&limit=10" \
  -H "x-access-key: YOUR_API_KEY"
LinkedIn Company Page analytics request
curl "{{API_BASE_URL}}/v1/analytics?source=platform&accountId=ACC_LI_ORG&platform=linkedin&limit=10" \
  -H "x-access-key: YOUR_API_KEY"
Error response example for date range exceeding 366 days
{
	"success": false,
	"message": "Date range cannot exceed 366 days."
}
Contract example 1
GET {{API_BASE_URL}}/v1/analytics
Contract example 2
curl "{{API_BASE_URL}}/v1/analytics?postId=69e0893109e2c65ae5957084" \
  -H "x-access-key: YOUR_API_KEY"
Single post analytics response example
{
	"success": true,
	"post": {
		"source": "postpeer",
		"postId": "69e0893109e2c65ae5957084",
		"content": "A short example update.",
		"publishedAt": "2026-04-16T20:56:00.747Z",
		"aggregated": {
			"impressions": 25,
			"reach": null,
			"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,
					"reach": null,
					"likes": 1,
					"comments": 0,
					"shares": null,
					"saves": 0,
					"clicks": null,
					"views": null,
					"engagementRate": null
				}
			}
		]
	}
}
Paginated analytics list response example
{
	"success": true,
	"total": 43,
	"page": 1,
	"limit": 10,
	"posts": [
		{
			"source": "postpeer",
			"postId": "69e0893109e2c65ae5957084",
			"content": "A short example update.",
			"publishedAt": "2026-04-16T20:56:00.747Z",
			"aggregated": {
				"impressions": 25,
				"reach": null,
				"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": { "...": "..." }
				}
			]
		}
	]
}
Account posts fetched directly from platform response example
{
	"success": true,
	"total": 2,
	"page": 1,
	"limit": 10,
	"posts": [
		{
			"source": "platform",
			"postId": null,
			"content": "A short example update.",
			"publishedAt": "2026-04-12T07:28:45Z",
			"aggregated": {
				"impressions": 4,
				"reach": null,
				"likes": 0,
				"comments": 0,
				"shares": null,
				"saves": 0,
				"clicks": 1,
				"views": null,
				"engagementRate": null
			},
			"platforms": [
				{
					"platform": "pinterest",
					"platformPostId": "1143210686684505466",
					"platformPostUrl": "https://www.pinterest.com/pin/1143210686684505466/",
					"metrics": { "...": "..." }
				}
			]
		}
	]
}
LinkedIn Company Page analytics response example
{
	"success": true,
	"total": 4,
	"page": 1,
	"limit": 10,
	"posts": [
		{
			"source": "platform",
			"postId": null,
			"content": "A short example update.",
			"publishedAt": "2026-05-22T15:11:33.803Z",
			"aggregated": {
				"impressions": 135,
				"reach": 59,
				"likes": 8,
				"comments": 1,
				"shares": 0,
				"saves": null,
				"clicks": 11,
				"views": null,
				"engagementRate": 14.81
			},
			"platforms": [
				{
					"platform": "linkedin",
					"platformPostId": "urn:li:share:7464748344205279232",
					"platformPostUrl": "https://www.linkedin.com/feed/update/urn:li:share:7464748344205279232/",
					"metrics": { "...": "..." }
				}
			]
		}
	]
}