Analytics
Instagram post metrics, account insights with demographics, and follower counts.
Read views, reach, and interactions for Instagram photos, carousels, Reels, and Stories, plus account-level insights and follower counts. The connection needs the insights permission (instagram_business_manage_insights or instagram_manage_insights), which both connection types request.
Metrics
| Field | Instagram metric | Notes |
|---|---|---|
impressions | impressions, or views when Instagram no longer reports impressions | |
reach | reach | Unique accounts |
plays | views | Most useful for Reels |
likes | likes | null on Stories |
comments | comments | null on Stories |
shares | shares | |
saves | saved | null on Stories |
clicks | None | Always null |
engagement | total_interactions | Sum of likes, comments, shares, and saves when Instagram does not report a total |
Each media type exposes a different set. A metric Instagram does not report for that media is null, not 0.
Read Post Analytics
Pass the Onepostly post id, or a native Instagram media id with accountId. See Targeting Posts.
import { Configuration, AnalyticsApi } from "@onepostly/sdk";
const analyticsApi = new AnalyticsApi(
new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);
const response = await analyticsApi.getAnalytics({
post: "1699f415-7fb6-43f4-9d2a-c447491f32a8",
metrics: "views,reach,profile_views",
period: "day",
});
console.log(response);{
"analytics": {
"post": "1699f415-7fb6-43f4-9d2a-c447491f32a8",
"status": "ready",
"fetchedAt": "2026-08-25T10:00:00.000Z",
"subjects": [
{
"scope": "destination",
"subjectId": "d4e5f6a7-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
"accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
"platform": "instagram",
"externalPostId": "17895695668004550",
"status": "ready",
"metrics": {
"impressions": 1234,
"reach": 987,
"likes": 123,
"comments": 12,
"shares": 4,
"saves": 2,
"plays": 456,
"engagement": 0.14
},
"fetchedAt": "2026-08-25T10:00:00.000Z",
"expiresAt": "2026-09-01T10:00:00.000Z",
"error": null,
"externalUrl": "https://www.instagram.com/p/17895695668004550/"
}
]
}
}Use Daily Timeline for day-by-day values.
Stories
Instagram reports Story metrics only while the Story is live (24 hours). To read a Story you did not publish through Onepostly, list active Stories with kind=stories and pass each id as post with accountId.
import { Configuration, ConnectionsApi } from "@onepostly/sdk";
const connectionsApi = new ConnectionsApi(
new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);
const response = await connectionsApi.listConnectionMedia({
id: "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
limit: 20,
kind: "stories",
audioType: "music",
});
console.log(response);{
"accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
"platform": "tiktok",
"items": [
{
"id": "7412345678901234567",
"title": "My trip",
"description": "Weekend recap #travel",
"coverUrl": "https://cdn.onepostly.com/media/cover.jpg",
"shareUrl": "https://www.tiktok.com/@you/video/7412345678901234567",
"createdAt": "2026-08-20T10:00:00.000Z",
"durationSec": 42,
"metrics": {
"likes": 123,
"comments": 12,
"shares": 4,
"views": 4567
}
}
],
"nextCursor": "20"
}Account Stats
Account Insights
Pass accountId without post to get live account insights. The default metrics are views, reach, profile_views, and accounts_engaged; pick others with metrics (comma-separated) and set period, since, and until. For demographics, set breakdown (age, city, country, follower_type, media_product_type) and timeframe (this_week, this_month, last_30_days). The response has rows for the metrics and demographics for the breakdowns.
import { Configuration, AnalyticsApi } from "@onepostly/sdk";
const analyticsApi = new AnalyticsApi(
new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);
const response = await analyticsApi.getAnalytics({
post: "1699f415-7fb6-43f4-9d2a-c447491f32a8",
accountId: "YOUR_INSTAGRAM_ACCOUNT_ID",
metrics: "views,reach,profile_views",
period: "day",
breakdown: "country",
timeframe: "last_30_days",
});
console.log(response);{
"analytics": {
"post": "1699f415-7fb6-43f4-9d2a-c447491f32a8",
"status": "ready",
"fetchedAt": "2026-08-25T10:00:00.000Z",
"subjects": [
{
"scope": "destination",
"subjectId": "d4e5f6a7-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
"accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
"platform": "instagram",
"externalPostId": "17895695668004550",
"status": "ready",
"metrics": {
"impressions": 1234,
"reach": 987,
"likes": 123,
"comments": 12,
"shares": 4,
"saves": 2,
"plays": 456,
"engagement": 0.14
},
"fetchedAt": "2026-08-25T10:00:00.000Z",
"expiresAt": "2026-09-01T10:00:00.000Z",
"error": null,
"externalUrl": "https://www.instagram.com/p/17895695668004550/"
}
]
}
}Follower Counts
Returns live counts: followerCount, followingCount, and videoCount (the total number of media on the account, photos included). likesCount is always null on Instagram.
import { Configuration, ConnectionsApi } from "@onepostly/sdk";
const connectionsApi = new ConnectionsApi(
new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);
const response = await connectionsApi.getConnectionStats({
id: "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
include: "messenger-profile,reviews",
limit: 20,
});
console.log(response);{
"accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
"platform": "instagram",
"status": "ready",
"stats": {
"followerCount": 1234,
"followingCount": 56,
"likesCount": 7890,
"videoCount": 12
},
"fetchedAt": "2026-08-25T10:00:00.000Z"
}Analytics Status
A post read right after publishing is usually pending while Instagram prepares its metrics; read it again later. A Story read after it expires may return no metrics. See Analytics Status.
Errors
| Code | Cause | Fix |
|---|---|---|
NOT_PUBLISHED | The destination has not published yet | Read again after the destination is published |
ANALYTICS_PENDING | Instagram has no metrics for the media yet | Read again later |
ANALYTICS_PERMISSION | The connection lacks the insights permission | Reconnect the account |
POST_NOT_FOUND | The media was deleted from Instagram | None. The post no longer exists |
RATE_LIMITED | Instagram throttled insights for this account | Read again later |
ANALYTICS_FAILED | Instagram returned an error for this media | Read again later; contact support if it keeps failing |