Instagram Analytics API
The Instagram Analytics API brings Instagram content performance, account-wide reach, follower count, and audience demographics into a product, reporting workflow, automation, or AI system through one API.
curl -X GET "{{API_BASE_URL}}/v1/analytics/?source=platform&platform=instagram&accountId=ig_456&limit=10&page=1" \
-H "x-access-key: your-api-key"curl -X GET "{{API_BASE_URL}}/v1/analytics/?source=platform&platform=instagram&accountId=ig_456&limit=10&pa…
-H "x-access-key: your-api-key"
Use it to track reach, saves, shares, and views for individual content, measure account-wide performance, and understand who is being reached without building a separate integration for each data type.
What the Instagram Analytics API returns and when to use each analytics type
Choose the analytics type by the question you need to answer. Use content analytics when you need Instagram content performance for a specific post, Reel, Story, or carousel, including reach, likes, comments, shares, saves, and views. Use account insights when you need a period view of how the whole account performed, covering measures such as profile views, profile link taps, follows and unfollows, reposts, replies, shares, saves, comments, likes, total interactions, accounts engaged, views, and reach. Use the follower count endpoint when you only need a current audience-size snapshot, and use audience demographics when you need follower, engaged-audience, or reached-audience breakdowns by age, city, country, and gender.
Exact captured request and response contract
The captured contract uses GET /v1/analytics/ with source, platform, accountId, limit, and page query parameters, authenticated with the x-access-key header. The Recent Media request example and the 202 response example are shown in the code examples titled Recent Media request and Recent Media response (202). Treat a 202 response as the captured success shape for this example, and validate success, total, page, limit, and the posts array before rendering metrics. If the request fails, check the accountId, the platform value, pagination values, and authentication header first, then check whether the connected account is a supported professional account.
Field map for content metrics
Each post in the response contains source, postId, content, publishedAt, an aggregated metrics object, and a platforms array. The aggregated object and each platform metrics object use the same metric fields: impressions, reach, likes, comments, shares, saves, clicks, views, and engagementRate. Several fields can be null, including impressions, clicks, engagementRate, and postId when source is platform, so your code should handle null values explicitly rather than assuming every metric is present. The platforms array identifies the Instagram entry with platform, platformPostId, platformPostUrl, and its own metrics object, which lets you keep per-platform values separate from the aggregated values.
Reporting-period and account-type limits
Content analytics uses fromDate and toDate with a maximum 366-day range. Instagram account insights use since and until with a maximum 90-day range, so do not reuse the content date parameters for account insights or assume the longer range applies to both. A professional Instagram account is required, and the connection uses Instagram Login, so a linked Facebook Page is not required. The follower endpoint returns only the current follower count, not historical follower growth, so store recurring snapshots yourself if you need a growth trend. Audience demographics require a sufficient audience, return up to 45 entries per dimension, and may be delayed by up to 48 hours.
Audience demographics and follower-count behavior
Audience demographics can be requested for followers, the engaged audience, or the reached audience, broken down by age, city, country, and gender for supported Instagram professional accounts. Use these breakdowns to decide which segments to prioritize in reporting, but design your UI to tolerate delayed or missing demographic data and to cap displayed entries at 45 per dimension. For follower count, treat each call as a point-in-time snapshot and record the retrieval time alongside the value so later comparisons are meaningful.
Integration checklist and capability gaps
Before integrating, confirm the connected account is a professional Instagram account, confirm the accountId you will send, and decide which analytics type each screen needs: content analytics for per-post performance, account insights for account-wide reach and interactions, follower count for a current snapshot, or audience demographics for segment breakdowns. Build failure checks for null metrics, pagination boundaries using total, page, and limit, date ranges that exceed 366 days for content or 90 days for account insights, and delayed demographic data. Each successful Instagram analytics request costs 1 credit under the captured contract, so cache responses where your reporting workflow allows it and avoid polling follower count or demographics more often than your product needs. The same API can be called from a developer stack with REST, from no-code automation tools, or from AI agents and MCP workflows, as long as each caller sends the same authenticated request and handles the same response fields.
| Field | Type / example | Requiredness / notes | Purpose |
|---|---|---|---|
| source | string, e.g. platform | Captured in request; use source=platform to pull from the connected account | Selects content source |
| platform | string, e.g. instagram | Captured in request | Selects Instagram |
| accountId | string, e.g. ig_456 | Captured in request; connected Instagram account identifier | Identifies the connected account |
| limit | integer, e.g. 10 | Captured in request; echoed in response | Page size |
| page | integer, e.g. 1 | Captured in request; echoed in response | Pagination page |
| fromDate | date string | Named for content analytics; maximum 366-day range with toDate | Content reporting start |
| toDate | date string | Named for content analytics; maximum 366-day range with fromDate | Content reporting end |
| since | date string | Named for Instagram account insights; maximum 90-day range with until | Account insights start |
| until | date string | Named for Instagram account insights; maximum 90-day range with since | Account insights end |
Captured parameters from the GET /v1/analytics/ sample and named date fields from source text; endpoint-specific parameters for account insights, follower count, and demographics are not confirmed in captured code blocks and are not invented here.
| Field | Type | Nullability | Notes |
|---|---|---|---|
| success | boolean | Not null in example | Request success flag |
| total | integer | Not null in example | Total matching posts |
| page | integer | Not null in example | Current page |
| limit | integer | Not null in example | Page size |
| posts[].source | string | Not null in example | e.g. platform |
| posts[].postId | string | Nullable; null in example | Null when source is platform |
| posts[].content | string | Not null in example | Post content text |
| posts[].publishedAt | string (ISO 8601) | Not null in example | Publish timestamp |
| posts[].aggregated.impressions | integer | Nullable; null in example | Aggregated impressions |
| posts[].aggregated.reach | integer | Not null in example | Aggregated reach |
| posts[].aggregated.likes | integer | Not null in example | Aggregated likes |
| posts[].aggregated.comments | integer | Not null in example | Aggregated comments |
| posts[].aggregated.shares | integer | Not null in example | Aggregated shares |
| posts[].aggregated.saves | integer | Not null in example | Aggregated saves |
| posts[].aggregated.clicks | integer | Nullable; null in example | Aggregated clicks |
| posts[].aggregated.views | integer | Not null in example | Aggregated views |
| posts[].aggregated.engagementRate | number | Nullable; null in example | Aggregated engagement rate |
| posts[].platforms[].platform | string | Not null in example | e.g. instagram |
| posts[].platforms[].platformPostId | string | Not null in example | Platform post identifier |
| posts[].platforms[].platformPostUrl | string (URL) | Not null in example | Platform post URL |
| posts[].platforms[].metrics | object | Same metric fields as aggregated | Per-platform metrics |
From the captured 202 response example.
| Analytics type | Use it when | Reporting period | Key limits |
|---|---|---|---|
| Content analytics | You need per-post Instagram content performance: reach, saves, shares, views, likes, comments | fromDate to toDate, maximum 366 days | Use source=platform with accountId for supported media not published through the API |
| Account insights | You need account-wide reach, views, accounts engaged, total interactions, profile views | since to until, maximum 90 days | Professional account required |
| Follower count | You need a current audience-size snapshot | Point in time | No historical follower growth; store snapshots yourself |
| Audience demographics | You need follower, engaged, or reached audience breakdowns | As returned for the account | By age, city, country, gender; up to 45 entries per dimension; may be delayed up to 48 hours; sufficient audience required |
Endpoint-specific paths and response fields for account insights, follower count, and demographics are not in captured code blocks; this matrix uses only source-described behavior.
| Check | Failure signal | Action |
|---|---|---|
| Authentication | Request rejected without a valid key | Send the x-access-key header with a valid API key |
| Account selection | Empty or wrong results | Verify accountId belongs to the connected Instagram account and platform=instagram |
| Date range | Range exceeds the limit | Keep content analytics within 366 days and account insights within 90 days |
| Account type | Insights or demographics unavailable | Confirm a professional Instagram account is connected |
| Null metrics | impressions, clicks, engagementRate, or postId is null | Handle null explicitly; do not assume every metric is present |
| Follower history | No past values returned | Store recurring follower count snapshots with retrieval timestamps |
| Demographics delay | Missing or stale segment data | Retry later; data may be delayed up to 48 hours and capped at 45 entries per dimension |
Derived from captured limits and response nullability.
Frequently asked questions
Can I retrieve analytics for Instagram content I did not publish through the API?
Yes. Set source=platform, platform=instagram, and the connected accountId, and the API returns supported media directly from that Instagram account, including items not published through the API.
Can I retrieve account-wide Instagram insights?
Yes. The account-insights endpoint covers measures such as profile views, profile link taps, follows and unfollows, reposts, replies, shares, saves, comments, likes, total interactions, accounts engaged, views, and reach.
How far back can I retrieve Instagram analytics?
Content analytics allows up to 366 days when you pass fromDate and toDate. Account insights are separate: since and until are limited to 90 days.
Can I retrieve historical Instagram follower growth?
No. That endpoint gives only the present follower count. If you need a trend, save each snapshot with its retrieval time in your own system.
What Instagram audience demographics can I retrieve?
Breakdowns are available for followers, engaged audience, or reached audience, split by gender, country, city, and age, for supported professional accounts. The audience must be large enough, each dimension returns at most 45 entries, and data can lag by as much as 48 hours.
What type of Instagram account do I need?
A professional Instagram account is required. Connection uses Instagram Login, so a linked Facebook Page is not required.
How much does an Instagram analytics request cost?
Each successful Instagram analytics request costs 1 credit under the captured contract.
Can agencies use Instagram analytics for client reporting?
Yes. Content analytics, account-wide insights, follower count, and audience demographics can be combined to build Instagram performance dashboards and reporting workflows for connected client accounts.
{
"success": true,
"total": 1,
"page": 1,
"limit": 10,
"posts": [
{
"source": "platform",
"postId": null,
"content": "A short example update.",
"publishedAt": "2026-08-28T14:30:00Z",
"aggregated": {
"impressions": null,
"reach": 4800,
"likes": 312,
"comments": 24,
"shares": 12,
"saves": 41,
"clicks": null,
"views": 2100,
"engagementRate": null
},
"platforms": [
{
"platform": "instagram",
"platformPostId": "17890012345678",
"platformPostUrl": "https://www.instagram.com/p/ABC123/",
"metrics": {
"impressions": null,
"reach": 4800,
"likes": 312,
"comments": 24,
"shares": 12,
"saves": 41,
"clicks": null,
"views": 2100,
"engagementRate": null
}
}
]
}
]
}