Skip to content

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.

Query parameters
ParameterRequiredTypeDefault / allowed valuesDescription
accountIdRequiredstring—Integration ID for the connected Instagram account.
metricOptionalstringDefault "follower_demographics"; "follower_demographics" | "engaged_audience_demographics" | "reached_audience_demographics"Audience whose demographic data should be returned.
breakdownOptionalstringDefault "age,city,country,gender"Comma-separated demographic dimensions: age, city, country, gender.
timeframeOptionalstringDefault "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}}.

200 response fields
FieldRequiredTypeNotes
successRequiredbooleantrue
accountIdRequiredstringEchoed integration ID.
platformRequiredstring"instagram"
metricRequiredstring"follower_demographics" | "engaged_audience_demographics" | "reached_audience_demographics"
timeframeRequiredstring"this_week" | "this_month"
demographicsRequiredobjectObject with optional age, city, country, gender arrays.
demographics.age[]Optional array itemobjectdimension: string (required); value: number (required)
demographics.city[]Optional array itemobjectdimension: string (required); value: number (required)
demographics.country[]Optional array itemobjectdimension: string (required); value: number (required)
demographics.gender[]Optional array itemobjectdimension: string (required); value: number (required)
noteRequiredstringNote string returned with the response.

Exact source contract parity for the 200 response.

Error status matrix
StatusContent typeBody shapeSpecific message supplied
400application/json{success, message}Not supplied
402application/json{success, message}Not supplied
403application/json{success, message}Not supplied
404application/json{success, message}Not supplied
502application/json{success, message}Not supplied

Source supplies only the {success, message} shape; no specific messages invented.

Request example
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>"
200 response example
{
  "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"
}
Error response shape for 400, 402, 403, 404 and 502
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
accountId#1accountIdstring__0YesIntegration ID for the connected Instagram account.
metric#2metricstring__0NoAudience whose demographic data should be returned.kind: schemaDefault; value: "follower_demographics"
metric#2metric[variant1]string__0_extends:__1Audience whose demographic data should be returned.kind: schemaDefault; value: "follower_demographics" | kind: schemaValueIn; value: "follower_demographics"
metric#2metric[variant2]string__0_extends:__2Audience whose demographic data should be returned.kind: schemaDefault; value: "follower_demographics" | kind: schemaValueIn; value: "engaged_audience_demographics"
metric#2metric[variant3]string__0_extends:__3Audience whose demographic data should be returned.kind: schemaDefault; value: "follower_demographics" | kind: schemaValueIn; value: "reached_audience_demographics"
breakdown#3breakdownstring__0NoComma-separated demographic dimensions: age, city, country, gender. Defaults to all four.kind: schemaDefault; value: "age,city,country,gender"
timeframe#4timeframestring__0NoMeta demographic timeframe. this_week covers the last 7 days; this_month covers the last 30 days.kind: ; value: "this_month"
timeframe#4timeframe[variant1]string__0_extends:__1Meta 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#4timeframe[variant2]string__0_extends:__2Meta 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#5responseobject__0
response#5response.successboolean__1Yeskind: schemaValueIn; value: true
response#5response.accountIdstring__2Yes
response#5response.platformstring__3Yeskind: schemaValueIn; value: "instagram"
response#5response.metricstring__4Yes
response#5response.metric[variant1]string__4_extends:__5kind: schemaValueIn; value: "follower_demographics"
response#5response.metric[variant2]string__4_extends:__6kind: schemaValueIn; value: "engaged_audience_demographics"
response#5response.metric[variant3]string__4_extends:__7kind: schemaValueIn; value: "reached_audience_demographics"
response#5response.timeframestring__8Yes
response#5response.timeframe[variant1]string__8_extends:__9kind: schemaValueIn; value: "this_week"
response#5response.timeframe[variant2]string__8_extends:__10kind: schemaValueIn; value: "this_month"
response#5response.demographicsobject__11Yes
response#5response.demographics.agearray<object>__12No
response#5response.demographics.age[]object__13
response#5response.demographics.age[].dimensionstring__14Yes
response#5response.demographics.age[].valuenumber__15Yes
response#5response.demographics.cityarray<object>__16No
response#5response.demographics.city[]object__17
response#5response.demographics.city[].dimensionstring__18Yes
response#5response.demographics.city[].valuenumber__19Yes
response#5response.demographics.countryarray<object>__20No
response#5response.demographics.country[]object__21
response#5response.demographics.country[].dimensionstring__22Yes
response#5response.demographics.country[].valuenumber__23Yes
response#5response.demographics.genderarray<object>__24No
response#5response.demographics.gender[]object__25
response#5response.demographics.gender[].dimensionstring__26Yes
response#5response.demographics.gender[].valuenumber__27Yes
response#5response.notestring__28Yes
response#6responseobject__0
response#6response.successboolean__1Yes
response#6response.messagestring__2Yes