Skip to content

Instagram account insights API

The Instagram account insights API returns account-wide Instagram insights across feed, stories, explore, and profile activity for a connected Instagram account. Use it to retrieve aggregated or daily reach data over a configurable date range, with the date range defaulting to the last 30 days and not exceeding 90 days.

Get Instagram account insights

Use this operation when you need a single account-level view of Instagram performance rather than post-by-post detail. It covers activity surfaced through feed, stories, explore, and profile surfaces for the connected account identified by accountId. If you omit the date parameters, the window covers the last 30 days; any window you specify must stay within 90 days. Daily granularity is available only for reach, and Missing Meta metrics are omitted rather than reported as zero. A successful call costs 1 credit. The exact operation is GET {{API_BASE_URL}}/v1/analytics/instagram/account-insights.

Authorization

Send the access key in the x-access-key header. The header value is the token placeholder shown in the contract example, and the header is required for the call to be authorized.

Query Parameters

The required query parameter is accountId, the integration ID for the connected Instagram account. Optional parameters are metrics, since, until, metricType, and breakdown. See the query parameters table for requiredness, types, defaults, formats, and enum values.

Choosing metrics, date range, metricType and breakdown

Choose total_value when you need an aggregate for the requested range, and choose time_series when you need daily reach values. Only reach supports daily time-series output, so do not expect daily series for other metrics. Use breakdown only with metricType=total_value, because breakdown is only valid with that mode. Keep the requested range within 90 days, and remember that the default range is the last 30 days when since and until are omitted.

Response Body

A successful 200 response contains success, accountId, platform, dateRange, metricType, metrics, and dataDelay. The metrics object is keyed by metric name, and each entry can contain total, values, and breakdowns. The dataDelay field is returned as a string in the 200 response. See the request example and the 200 response example for the exact shapes.

200 application/json

The 200 application/json response is the success shape described above, with platform set to instagram and metricType set to total_value or time_series. Check the 200 response example for the full nested metrics structure, including values with date and value, and breakdowns with dimensionKeys and results.

400 application/json

The 400 application/json response uses the generic error body with success and message. No additional meaning for this status is documented here beyond the status code and body shape. See the error response example.

402 application/json

The 402 application/json response uses the generic error body with success and message. No additional meaning for this status is documented here beyond the status code and body shape. See the error response example.

403 application/json

The 403 application/json response uses the generic error body with success and message. No additional meaning for this status is documented here beyond the status code and body shape. See the error response example.

404 application/json

The 404 application/json response uses the generic error body with success and message. No additional meaning for this status is documented here beyond the status code and body shape. See the error response example.

502 application/json

The 502 application/json response uses the generic error body with success and message. No additional meaning for this status is documented here beyond the status code and body shape. See the error response example.

Behaviour notes: defaults, limits, missing metrics and credit cost

Before calling, confirm accountId is the integration ID for the connected Instagram account, confirm the date range does not exceed 90 days, and confirm breakdown is not combined with time_series. After a successful call, treat absent metrics as omitted missing data rather than zero values, and check dataDelay in the response. Each successful call costs 1 credit.

Query parameters
ParameterRequiredTypeDefault / Format / EnumDescription
accountIdRequiredstring-Integration ID for the connected Instagram account.
metricsOptionalstringDefault "reach,views,accounts_engaged,total_interactions"Comma-separated account metrics. Valid metrics: reach, views, accounts_engaged, total_interactions, comments, likes, saves, shares, replies, reposts, follows_and_unfollows, profile_links_taps, profile_views.
sinceOptionalstringFormat date (YYYY-MM-DD); defaults to 30 days agoStart date (YYYY-MM-DD). Defaults to 30 days ago.
untilOptionalstringFormat date (YYYY-MM-DD); defaults to todayEnd date (YYYY-MM-DD). Defaults to today.
metricTypeOptionalstringDefault "total_value"; enum "total_value", "time_series"total_value returns an aggregate; time_series returns daily reach values.
breakdownOptionalstringEnum "media_product_type", "follow_type", "follower_type", "contact_button_type"; only valid with metricType=total_valueOptional Meta breakdown dimension. Only valid with metricType=total_value.

Exact contract preserved from source; breakdown enum values from typed contract.

200 response fields
FieldRequiredTypeNotes
successRequiredbooleanValue true in the 200 example.
accountIdRequiredstringIntegration ID for the connected Instagram account.
platformRequiredstringValue "instagram".
dateRangeRequiredobjectContains since and until, both required strings with format date.
metricTypeRequiredstringEnum "total_value", "time_series".
metricsRequiredobjectKeyed by metric name; each entry has required total (number) and optional values and breakdowns.
metrics.[key: string].values[]Optionalarray<object>Each entry has required date (string, format date) and required value (number).
metrics.[key: string].breakdowns[]Optionalarray<object>Each entry has required dimensionKeys (array<string>) and required results (array<object>).
metrics.[key: string].breakdowns[].results[]Optionalarray<object>Each entry has required dimensionValues (array<string>) and required value (number).
dataDelayRequiredstringReturned in the 200 response.

Exact 200 response fields preserved from source.

Status codes and response bodies
StatusContent typeBody
200application/jsonSuccess body with success, accountId, platform, dateRange, metricType, metrics, dataDelay.
400application/jsonGeneric body with success (boolean) and message (string).
402application/jsonGeneric body with success (boolean) and message (string).
403application/jsonGeneric body with success (boolean) and message (string).
404application/jsonGeneric body with success (boolean) and message (string).
502application/jsonGeneric body with success (boolean) and message (string).

Meanings beyond status and body shape are not documented in source and are not invented.

Request example
curl -X GET "{{API_BASE_URL}}/v1/analytics/instagram/account-insights?accountId=string"
200 response example
{
  "success": true,
  "accountId": "string",
  "platform": "instagram",
  "dateRange": {
    "since": "2019-08-24",
    "until": "2019-08-24"
  },
  "metricType": "total_value",
  "metrics": {
    "property1": {
      "total": 0,
      "values": [
        {
          "date": "2019-08-24",
          "value": 0
        }
      ],
      "breakdowns": [
        {
          "dimensionKeys": [
            "string"
          ],
          "results": [
            {
              "dimensionValues": [
                "string"
              ],
              "value": 0
            }
          ]
        }
      ]
    },
    "property2": {
      "total": 0,
      "values": [
        {
          "date": "2019-08-24",
          "value": 0
        }
      ],
      "breakdowns": [
        {
          "dimensionKeys": [
            "string"
          ],
          "results": [
            {
              "dimensionValues": [
                "string"
              ],
              "value": 0
            }
          ]
        }
      ]
    }
  },
  "dataDelay": "string"
}
Error response example for 400, 402, 403, 404 and 502
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
accountId#1accountIdstring__0YesIntegration ID for the connected Instagram account.
metrics#2metricsstring__0NoComma-separated account metrics. Valid metrics: reach, views, accounts_engaged, total_interactions, comments, likes, saves, shares, replies, reposts, follows_and_unfollows, profile_links_taps, profile_views.kind: schemaDefault; value: "reach,views,accounts_engaged,total_interactions"
since#3sincestring__0NoStart date (YYYY-MM-DD). Defaults to 30 days ago.kind: schemaFormat; value: date
until#4untilstring__0NoEnd date (YYYY-MM-DD). Defaults to today.kind: schemaFormat; value: date
metricType#5metricTypestring__0Nototal_value returns an aggregate; time_series returns daily reach values.kind: schemaDefault; value: "total_value"
metricType#5metricType[variant1]string__0_extends:__1total_value returns an aggregate; time_series returns daily reach values.kind: schemaDefault; value: "total_value" | kind: schemaValueIn; value: "total_value"
metricType#5metricType[variant2]string__0_extends:__2total_value returns an aggregate; time_series returns daily reach values.kind: schemaDefault; value: "total_value" | kind: schemaValueIn; value: "time_series"
breakdown#6breakdownstring__0NoOptional Meta breakdown dimension. Only valid with metricType=total_value.
breakdown#6breakdown[variant1]string__0_extends:__1Optional Meta breakdown dimension. Only valid with metricType=total_value.kind: schemaValueIn; value: "media_product_type"
breakdown#6breakdown[variant2]string__0_extends:__2Optional Meta breakdown dimension. Only valid with metricType=total_value.kind: schemaValueIn; value: "follow_type"
breakdown#6breakdown[variant3]string__0_extends:__3Optional Meta breakdown dimension. Only valid with metricType=total_value.kind: schemaValueIn; value: "follower_type"
breakdown#6breakdown[variant4]string__0_extends:__4Optional Meta breakdown dimension. Only valid with metricType=total_value.kind: schemaValueIn; value: "contact_button_type"
response#7responseobject__0
response#7response.successboolean__1Yeskind: schemaValueIn; value: true
response#7response.accountIdstring__2Yes
response#7response.platformstring__3Yeskind: schemaValueIn; value: "instagram"
response#7response.dateRangeobject__4Yes
response#7response.dateRange.sincestring__5Yeskind: schemaFormat; value: date
response#7response.dateRange.untilstring__6Yeskind: schemaFormat; value: date
response#7response.metricTypestring__7Yes
response#7response.metricType[variant1]string__7_extends:__8kind: schemaValueIn; value: "total_value"
response#7response.metricType[variant2]string__7_extends:__9kind: schemaValueIn; value: "time_series"
response#7response.metricsobject__10Yes
response#7response.metrics.[key: string]object__11No
response#7response.metrics.[key: string].totalnumber__12Yes
response#7response.metrics.[key: string].valuesarray<object>__13No
response#7response.metrics.[key: string].values[]object__14
response#7response.metrics.[key: string].values[].datestring__15Yeskind: schemaFormat; value: date
response#7response.metrics.[key: string].values[].valuenumber__16Yes
response#7response.metrics.[key: string].breakdownsarray<object>__17No
response#7response.metrics.[key: string].breakdowns[]object__18
response#7response.metrics.[key: string].breakdowns[].dimensionKeysarray<string>__19Yes
response#7response.metrics.[key: string].breakdowns[].dimensionKeys[]string__20
response#7response.metrics.[key: string].breakdowns[].resultsarray<object>__21Yes
response#7response.metrics.[key: string].breakdowns[].results[]object__22
response#7response.metrics.[key: string].breakdowns[].results[].dimensionValuesarray<string>__23Yes
response#7response.metrics.[key: string].breakdowns[].results[].dimensionValues[]string__24
response#7response.metrics.[key: string].breakdowns[].results[].valuenumber__25Yes
response#7response.dataDelaystring__26Yes
response#8responseobject__0
response#8response.successboolean__1Yes
response#8response.messagestring__2Yes