Skip to content

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.

Recent Media request
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"
Illustrative request
Example line 1

curl -X GET "{{API_BASE_URL}}/v1/analytics/?source=platform&platform=instagram&accountId=ig_456&limit=10&pa…

Illustrative request
Example line 2

-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.

Input contract for captured analytics parameters
FieldType / exampleRequiredness / notesPurpose
sourcestring, e.g. platformCaptured in request; use source=platform to pull from the connected accountSelects content source
platformstring, e.g. instagramCaptured in requestSelects Instagram
accountIdstring, e.g. ig_456Captured in request; connected Instagram account identifierIdentifies the connected account
limitinteger, e.g. 10Captured in request; echoed in responsePage size
pageinteger, e.g. 1Captured in request; echoed in responsePagination page
fromDatedate stringNamed for content analytics; maximum 366-day range with toDateContent reporting start
toDatedate stringNamed for content analytics; maximum 366-day range with fromDateContent reporting end
sincedate stringNamed for Instagram account insights; maximum 90-day range with untilAccount insights start
untildate stringNamed for Instagram account insights; maximum 90-day range with sinceAccount 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 map for the captured analytics response
FieldTypeNullabilityNotes
successbooleanNot null in exampleRequest success flag
totalintegerNot null in exampleTotal matching posts
pageintegerNot null in exampleCurrent page
limitintegerNot null in examplePage size
posts[].sourcestringNot null in examplee.g. platform
posts[].postIdstringNullable; null in exampleNull when source is platform
posts[].contentstringNot null in examplePost content text
posts[].publishedAtstring (ISO 8601)Not null in examplePublish timestamp
posts[].aggregated.impressionsintegerNullable; null in exampleAggregated impressions
posts[].aggregated.reachintegerNot null in exampleAggregated reach
posts[].aggregated.likesintegerNot null in exampleAggregated likes
posts[].aggregated.commentsintegerNot null in exampleAggregated comments
posts[].aggregated.sharesintegerNot null in exampleAggregated shares
posts[].aggregated.savesintegerNot null in exampleAggregated saves
posts[].aggregated.clicksintegerNullable; null in exampleAggregated clicks
posts[].aggregated.viewsintegerNot null in exampleAggregated views
posts[].aggregated.engagementRatenumberNullable; null in exampleAggregated engagement rate
posts[].platforms[].platformstringNot null in examplee.g. instagram
posts[].platforms[].platformPostIdstringNot null in examplePlatform post identifier
posts[].platforms[].platformPostUrlstring (URL)Not null in examplePlatform post URL
posts[].platforms[].metricsobjectSame metric fields as aggregatedPer-platform metrics

From the captured 202 response example.

Choosing between content analytics, account insights, follower count, and demographics
Analytics typeUse it whenReporting periodKey limits
Content analyticsYou need per-post Instagram content performance: reach, saves, shares, views, likes, commentsfromDate to toDate, maximum 366 daysUse source=platform with accountId for supported media not published through the API
Account insightsYou need account-wide reach, views, accounts engaged, total interactions, profile viewssince to until, maximum 90 daysProfessional account required
Follower countYou need a current audience-size snapshotPoint in timeNo historical follower growth; store snapshots yourself
Audience demographicsYou need follower, engaged, or reached audience breakdownsAs returned for the accountBy 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.

Failure and limit checks
CheckFailure signalAction
AuthenticationRequest rejected without a valid keySend the x-access-key header with a valid API key
Account selectionEmpty or wrong resultsVerify accountId belongs to the connected Instagram account and platform=instagram
Date rangeRange exceeds the limitKeep content analytics within 366 days and account insights within 90 days
Account typeInsights or demographics unavailableConfirm a professional Instagram account is connected
Null metricsimpressions, clicks, engagementRate, or postId is nullHandle null explicitly; do not assume every metric is present
Follower historyNo past values returnedStore recurring follower count snapshots with retrieval timestamps
Demographics delayMissing or stale segment dataRetry 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.

Recent Media response (202)
{
    "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
            }
          }
        ]
      }
    ]
}