Get Instagram demographics API
The Get Instagram demographics API lets a developer ask, for one connected Instagram account, how its audience splits across age, city, country, and gender. You choose which audience to describe — followers, people who engaged, or people who were reached — and which time window to use, then parse the grouped counts returned for each requested dimension.
Operation summary: GET {{API_BASE_URL}}/v1/analytics/instagram/demographics
Use GET {{API_BASE_URL}}/v1/analytics/instagram/demographics to fetch grouped audience data for a connected Instagram account. The three selectable audiences are follower_demographics, engaged_audience_demographics, and reached_audience_demographics, and they describe different populations, so pick the one matching the question you are answering. Responses are capped at 45 entries for any single dimension, a large enough audience is needed before data is available, and figures can lag by as much as 48 hours. The charge for one invocation is 1 credit.
Authorization
Authentication uses the x-access-key header, with the token supplied as its value. Keep that token out of URLs and logs. The field map below shows the header name and the placeholder form used in the contract.
Query parameters field map
One parameter is mandatory: accountId, typed as string, holding the integration identifier of the linked Instagram account. Three further parameters are optional. The metric parameter chooses the audience and falls back to follower_demographics when omitted. The breakdown parameter takes a comma-separated set of dimensions and falls back to age,city,country,gender. The timeframe parameter chooses between this_week, meaning the preceding 7 days, and this_month, meaning the preceding 30 days, with this_month as the fallback. Narrow breakdown to only the dimensions you will actually use, since every requested dimension comes back as its own array.
Response body: 200 application/json
On success the service answers with 200 and an application/json payload. Its top-level members are success, accountId, platform, metric, timeframe, demographics, and note. The platform member carries the literal value instagram. Inside demographics, each dimension you asked for appears as an array whose items pair a dimension string with a numeric value. When reading the payload, confirm success and platform first, then look only at the dimension keys present in your request. A dimension key that is absent should be treated as no data for that dimension, not as zero. The Request example and 200 response example show a complete call and a matching payload.
Error status matrix
Five failure statuses are documented: 400, 402, 403, 404, and 502, each with an application/json body. Every one of those bodies follows the same two-field layout illustrated in the Error response shape for 400, 402, 403, 404 and 502 example, namely success plus message. Because the contract gives no concrete message text for any of these statuses, client code should switch on the numeric status, display or log whatever message arrived, and refrain from assuming a finer-grained code. That approach keeps handling correct regardless of the wording the service returns.
Limits, checks, and data notes
Run through a short checklist before and after calling. Beforehand, verify that accountId identifies a connected Instagram account, that metric is one of the three documented audience values, that breakdown names only age, city, country, or gender, and that timeframe is this_week or this_month. Afterwards, check that the returned demographics object holds the keys you requested and that each item carries a string dimension alongside a number value. When numbers seem out of date, remember the possible lag of up to 48 hours, and when an account has too small an audience, the sufficient-audience condition may mean no usable breakdown is produced. Since each invocation costs 1 credit, repeating an identical call just to look for newer figures is wasteful.
| Parameter | Required | Type | Default / allowed values | Description |
|---|---|---|---|---|
| accountId | Required | string | — | Integration ID for the connected Instagram account. |
| metric | Optional | string | Default "follower_demographics"; "follower_demographics" | "engaged_audience_demographics" | "reached_audience_demographics" | Audience whose demographic data should be returned. |
| breakdown | Optional | string | Default "age,city,country,gender" | Comma-separated demographic dimensions: age, city, country, gender. |
| timeframe | Optional | string | Default "this_month"; "this_week" | "this_month" | Meta demographic timeframe. this_week covers the last 7 days; this_month covers the last 30 days. |
Exact source contract parity; origin is {{API_BASE_URL}}.
| Field | Required | Type | Notes |
|---|---|---|---|
| success | Required | boolean | true |
| accountId | Required | string | Echoed integration ID. |
| platform | Required | string | "instagram" |
| metric | Required | string | "follower_demographics" | "engaged_audience_demographics" | "reached_audience_demographics" |
| timeframe | Required | string | "this_week" | "this_month" |
| demographics | Required | object | Object with optional age, city, country, gender arrays. |
| demographics.age[] | Optional array item | object | dimension: string (required); value: number (required) |
| demographics.city[] | Optional array item | object | dimension: string (required); value: number (required) |
| demographics.country[] | Optional array item | object | dimension: string (required); value: number (required) |
| demographics.gender[] | Optional array item | object | dimension: string (required); value: number (required) |
| note | Required | string | Note string returned with the response. |
Exact source contract parity for the 200 response.
| Status | Content type | Body shape | Specific message supplied |
|---|---|---|---|
| 400 | application/json | {success, message} | Not supplied |
| 402 | application/json | {success, message} | Not supplied |
| 403 | application/json | {success, message} | Not supplied |
| 404 | application/json | {success, message} | Not supplied |
| 502 | application/json | {success, message} | Not supplied |
Source supplies only the {success, message} shape; no specific messages invented.
curl -X GET "{{API_BASE_URL}}/v1/analytics/instagram/demographics?accountId=string&metric=follower_demographics&breakdown=age,city,country,gender&timeframe=this_month" -H "x-access-key: <token>"{
"success": true,
"accountId": "string",
"platform": "instagram",
"metric": "follower_demographics",
"timeframe": "this_week",
"demographics": {
"age": [
{
"dimension": "string",
"value": 0
}
],
"city": [
{
"dimension": "string",
"value": 0
}
],
"country": [
{
"dimension": "string",
"value": 0
}
],
"gender": [
{
"dimension": "string",
"value": 0
}
]
},
"note": "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. | |
| metric#2 | metric | string | __0 | No | Audience whose demographic data should be returned. | kind: schemaDefault; value: "follower_demographics" |
| metric#2 | metric[variant1] | string | __0_extends:__1 | Audience whose demographic data should be returned. | kind: schemaDefault; value: "follower_demographics" | kind: schemaValueIn; value: "follower_demographics" | |
| metric#2 | metric[variant2] | string | __0_extends:__2 | Audience whose demographic data should be returned. | kind: schemaDefault; value: "follower_demographics" | kind: schemaValueIn; value: "engaged_audience_demographics" | |
| metric#2 | metric[variant3] | string | __0_extends:__3 | Audience whose demographic data should be returned. | kind: schemaDefault; value: "follower_demographics" | kind: schemaValueIn; value: "reached_audience_demographics" | |
| breakdown#3 | breakdown | string | __0 | No | Comma-separated demographic dimensions: age, city, country, gender. Defaults to all four. | kind: schemaDefault; value: "age,city,country,gender" |
| timeframe#4 | timeframe | string | __0 | No | Meta demographic timeframe. this_week covers the last 7 days; this_month covers the last 30 days. | kind: ; value: "this_month" |
| timeframe#4 | timeframe[variant1] | string | __0_extends:__1 | Meta demographic timeframe. this_week covers the last 7 days; this_month covers the last 30 days. | kind: ; value: "this_month" | kind: ; value: "this_week" | |
| timeframe#4 | timeframe[variant2] | string | __0_extends:__2 | Meta demographic timeframe. this_week covers the last 7 days; this_month covers the last 30 days. | kind: ; value: "this_month" | kind: ; value: "this_month" | |
| response#5 | response | object | __0 | |||
| response#5 | response.success | boolean | __1 | Yes | kind: schemaValueIn; value: true | |
| response#5 | response.accountId | string | __2 | Yes | ||
| response#5 | response.platform | string | __3 | Yes | kind: schemaValueIn; value: "instagram" | |
| response#5 | response.metric | string | __4 | Yes | ||
| response#5 | response.metric[variant1] | string | __4_extends:__5 | kind: schemaValueIn; value: "follower_demographics" | ||
| response#5 | response.metric[variant2] | string | __4_extends:__6 | kind: schemaValueIn; value: "engaged_audience_demographics" | ||
| response#5 | response.metric[variant3] | string | __4_extends:__7 | kind: schemaValueIn; value: "reached_audience_demographics" | ||
| response#5 | response.timeframe | string | __8 | Yes | ||
| response#5 | response.timeframe[variant1] | string | __8_extends:__9 | kind: schemaValueIn; value: "this_week" | ||
| response#5 | response.timeframe[variant2] | string | __8_extends:__10 | kind: schemaValueIn; value: "this_month" | ||
| response#5 | response.demographics | object | __11 | Yes | ||
| response#5 | response.demographics.age | array<object> | __12 | No | ||
| response#5 | response.demographics.age[] | object | __13 | |||
| response#5 | response.demographics.age[].dimension | string | __14 | Yes | ||
| response#5 | response.demographics.age[].value | number | __15 | Yes | ||
| response#5 | response.demographics.city | array<object> | __16 | No | ||
| response#5 | response.demographics.city[] | object | __17 | |||
| response#5 | response.demographics.city[].dimension | string | __18 | Yes | ||
| response#5 | response.demographics.city[].value | number | __19 | Yes | ||
| response#5 | response.demographics.country | array<object> | __20 | No | ||
| response#5 | response.demographics.country[] | object | __21 | |||
| response#5 | response.demographics.country[].dimension | string | __22 | Yes | ||
| response#5 | response.demographics.country[].value | number | __23 | Yes | ||
| response#5 | response.demographics.gender | array<object> | __24 | No | ||
| response#5 | response.demographics.gender[] | object | __25 | |||
| response#5 | response.demographics.gender[].dimension | string | __26 | Yes | ||
| response#5 | response.demographics.gender[].value | number | __27 | Yes | ||
| response#5 | response.note | string | __28 | Yes | ||
| response#6 | response | object | __0 | |||
| response#6 | response.success | boolean | __1 | Yes | ||
| response#6 | response.message | string | __2 | Yes |