Instagram
Insights
Analytics and normalized metrics for Instagram media.
Fetch media analytics for a published Instagram destination. Metrics are mapped into the shared Onepostly insights shape used across platforms.
Requires instagram_business_manage_insights.
Request
curl "https://api.onepostly.com/v1/posts/POST_ID/insights" \
-H "x-api-key: op_YOUR_KEY"Optional: ?refresh=1 (or refresh=true) to bypass cache and refetch from Instagram.
Response includes one entry per destination under insights.destinations.
Normalized fields
| Field | Notes |
|---|---|
impressions | Impressions or views, depending on product |
reach | Reach when available |
likes | Like count |
comments | Comment count |
shares | Share count |
saves | Saves |
plays | Views / plays (useful for Reels) |
engagement | Total interactions, or sum of likes + comments + shares + saves (null if all inputs are null) |
Missing values are null (not 0), unless a composite field deliberately sums available siblings.
Available metrics vary by product (feed, Reels, Stories). Stories typically have a shorter-lived / sparser set.
Example response shape
{
"insights": {
"postId": "…",
"status": "ready",
"destinations": [
{
"destinationId": "…",
"platform": "instagram",
"status": "ready",
"metrics": {
"impressions": 4200,
"reach": 3100,
"likes": 180,
"comments": 12,
"shares": 9,
"saves": 44,
"plays": 4200,
"engagement": 245
}
}
]
}
}Destination-level statuses may also be pending, failed, or unavailable (e.g. not published yet).
Errors / statuses
| Code / status | Meaning |
|---|---|
NOT_PUBLISHED | Destination not published yet |
INSIGHTS_PERMISSION | Missing insights scope → reconnect |
INSIGHTS_PENDING | Metrics not ready yet — retry later |
INSIGHTS_FAILED | Hard failure fetching metrics |
MISSING_EXTERNAL_ID | No media id on the destination |
Tips
- Calling shortly after publish may return
pending— Instagram needs time to aggregate - Prefer
?refresh=1only when you need fresh numbers; otherwise cached snapshots are returned - For Stories, expect a shorter-lived / sparser metric set than feed or Reels