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.
| Parameter | Required | Type | Default / Format / Enum | Description |
|---|---|---|---|---|
| accountId | Required | string | - | Integration ID for the connected Instagram account. |
| metrics | Optional | string | Default "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. |
| since | Optional | string | Format date (YYYY-MM-DD); defaults to 30 days ago | Start date (YYYY-MM-DD). Defaults to 30 days ago. |
| until | Optional | string | Format date (YYYY-MM-DD); defaults to today | End date (YYYY-MM-DD). Defaults to today. |
| metricType | Optional | string | Default "total_value"; enum "total_value", "time_series" | total_value returns an aggregate; time_series returns daily reach values. |
| breakdown | Optional | string | Enum "media_product_type", "follow_type", "follower_type", "contact_button_type"; only valid with metricType=total_value | Optional Meta breakdown dimension. Only valid with metricType=total_value. |
Exact contract preserved from source; breakdown enum values from typed contract.
| Field | Required | Type | Notes |
|---|---|---|---|
| success | Required | boolean | Value true in the 200 example. |
| accountId | Required | string | Integration ID for the connected Instagram account. |
| platform | Required | string | Value "instagram". |
| dateRange | Required | object | Contains since and until, both required strings with format date. |
| metricType | Required | string | Enum "total_value", "time_series". |
| metrics | Required | object | Keyed by metric name; each entry has required total (number) and optional values and breakdowns. |
| metrics.[key: string].values[] | Optional | array<object> | Each entry has required date (string, format date) and required value (number). |
| metrics.[key: string].breakdowns[] | Optional | array<object> | Each entry has required dimensionKeys (array<string>) and required results (array<object>). |
| metrics.[key: string].breakdowns[].results[] | Optional | array<object> | Each entry has required dimensionValues (array<string>) and required value (number). |
| dataDelay | Required | string | Returned in the 200 response. |
Exact 200 response fields preserved from source.
| Status | Content type | Body |
|---|---|---|
| 200 | application/json | Success body with success, accountId, platform, dateRange, metricType, metrics, dataDelay. |
| 400 | application/json | Generic body with success (boolean) and message (string). |
| 402 | application/json | Generic body with success (boolean) and message (string). |
| 403 | application/json | Generic body with success (boolean) and message (string). |
| 404 | application/json | Generic body with success (boolean) and message (string). |
| 502 | application/json | Generic body with success (boolean) and message (string). |
Meanings beyond status and body shape are not documented in source and are not invented.
curl -X GET "{{API_BASE_URL}}/v1/analytics/instagram/account-insights?accountId=string"{
"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"
}{
"success": true,
"message": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| accountId#1 | accountId | string | __0 | Yes | Integration ID for the connected Instagram account. | |
| metrics#2 | metrics | string | __0 | No | 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. | kind: schemaDefault; value: "reach,views,accounts_engaged,total_interactions" |
| since#3 | since | string | __0 | No | Start date (YYYY-MM-DD). Defaults to 30 days ago. | kind: schemaFormat; value: date |
| until#4 | until | string | __0 | No | End date (YYYY-MM-DD). Defaults to today. | kind: schemaFormat; value: date |
| metricType#5 | metricType | string | __0 | No | total_value returns an aggregate; time_series returns daily reach values. | kind: schemaDefault; value: "total_value" |
| metricType#5 | metricType[variant1] | string | __0_extends:__1 | total_value returns an aggregate; time_series returns daily reach values. | kind: schemaDefault; value: "total_value" | kind: schemaValueIn; value: "total_value" | |
| metricType#5 | metricType[variant2] | string | __0_extends:__2 | total_value returns an aggregate; time_series returns daily reach values. | kind: schemaDefault; value: "total_value" | kind: schemaValueIn; value: "time_series" | |
| breakdown#6 | breakdown | string | __0 | No | Optional Meta breakdown dimension. Only valid with metricType=total_value. | |
| breakdown#6 | breakdown[variant1] | string | __0_extends:__1 | Optional Meta breakdown dimension. Only valid with metricType=total_value. | kind: schemaValueIn; value: "media_product_type" | |
| breakdown#6 | breakdown[variant2] | string | __0_extends:__2 | Optional Meta breakdown dimension. Only valid with metricType=total_value. | kind: schemaValueIn; value: "follow_type" | |
| breakdown#6 | breakdown[variant3] | string | __0_extends:__3 | Optional Meta breakdown dimension. Only valid with metricType=total_value. | kind: schemaValueIn; value: "follower_type" | |
| breakdown#6 | breakdown[variant4] | string | __0_extends:__4 | Optional Meta breakdown dimension. Only valid with metricType=total_value. | kind: schemaValueIn; value: "contact_button_type" | |
| response#7 | response | object | __0 | |||
| response#7 | response.success | boolean | __1 | Yes | kind: schemaValueIn; value: true | |
| response#7 | response.accountId | string | __2 | Yes | ||
| response#7 | response.platform | string | __3 | Yes | kind: schemaValueIn; value: "instagram" | |
| response#7 | response.dateRange | object | __4 | Yes | ||
| response#7 | response.dateRange.since | string | __5 | Yes | kind: schemaFormat; value: date | |
| response#7 | response.dateRange.until | string | __6 | Yes | kind: schemaFormat; value: date | |
| response#7 | response.metricType | string | __7 | Yes | ||
| response#7 | response.metricType[variant1] | string | __7_extends:__8 | kind: schemaValueIn; value: "total_value" | ||
| response#7 | response.metricType[variant2] | string | __7_extends:__9 | kind: schemaValueIn; value: "time_series" | ||
| response#7 | response.metrics | object | __10 | Yes | ||
| response#7 | response.metrics.[key: string] | object | __11 | No | ||
| response#7 | response.metrics.[key: string].total | number | __12 | Yes | ||
| response#7 | response.metrics.[key: string].values | array<object> | __13 | No | ||
| response#7 | response.metrics.[key: string].values[] | object | __14 | |||
| response#7 | response.metrics.[key: string].values[].date | string | __15 | Yes | kind: schemaFormat; value: date | |
| response#7 | response.metrics.[key: string].values[].value | number | __16 | Yes | ||
| response#7 | response.metrics.[key: string].breakdowns | array<object> | __17 | No | ||
| response#7 | response.metrics.[key: string].breakdowns[] | object | __18 | |||
| response#7 | response.metrics.[key: string].breakdowns[].dimensionKeys | array<string> | __19 | Yes | ||
| response#7 | response.metrics.[key: string].breakdowns[].dimensionKeys[] | string | __20 | |||
| response#7 | response.metrics.[key: string].breakdowns[].results | array<object> | __21 | Yes | ||
| response#7 | response.metrics.[key: string].breakdowns[].results[] | object | __22 | |||
| response#7 | response.metrics.[key: string].breakdowns[].results[].dimensionValues | array<string> | __23 | Yes | ||
| response#7 | response.metrics.[key: string].breakdowns[].results[].dimensionValues[] | string | __24 | |||
| response#7 | response.metrics.[key: string].breakdowns[].results[].value | number | __25 | Yes | ||
| response#7 | response.dataDelay | string | __26 | Yes | ||
| response#8 | response | object | __0 | |||
| response#8 | response.success | boolean | __1 | Yes | ||
| response#8 | response.message | string | __2 | Yes |