> ## Documentation Index
> Fetch the complete documentation index at: https://docs.creatordb.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Audience Demographics
> Retrieve audience demographic insights for a specified Instagram creator, including country distribution, gender breakdown, and age composition. This endpoint provides detailed audience analytics to help understand creator reach, evaluate audience alignment, and support data‑driven influencer selection and campaign targeting.
Optionally pass `fields` in the request body to return only a subset of demographic fields. You are billed for the fields you request, capped at the full-bundle price. Fractional calls must be enabled on your API key. Otherwise, a request that includes `fields` returns a `400` error (`FractionalCallsNotEnabled`). Per-field costs are not published yet. For how fractional calls work, see [Fractional Calls](/api-v3/fractional-calls).
## OpenAPI
````yaml /api-v3/api-v3.yaml post /instagram/audience
openapi: 3.1.0
info:
version: 1.0.0
title: CreatorDB Headless API V3
description: '# CreatorDB Headless API V3'
contact:
name: CreatorDB
url: https://www.creatordb.app
email: support@creatordb.app
license:
url: http://www.apache.org/licenses/LICENSE-2.0.html
name: Apache 2.0
servers:
- url: https://apiv3.creatordb.app
description: Production Environment (CreatorDB Headless API V3)
security:
- ApiKeyAuth: []
tags:
- name: Brand
description: Brand analysis endpoints including sponsor search and brand reports.
- name: Facebook
description: Facebook creator data endpoints with metrics and search capabilities.
- name: General Operations
description: >-
General-purpose endpoints such as API status, content retrieval, and
cross-platform operations.
- name: Instagram
description: >-
Instagram creator data endpoints with metrics and advanced search
capabilities.
- name: Niches
description: >-
Niche-related endpoints for content category analysis and related
searches.
- name: Threads
description: Threads creator data endpoints with basic metrics and historical data.
- name: TikTok
description: >-
TikTok creator data endpoints with metrics and advanced search
functionality.
- name: Topic
description: Topic-based analysis and reporting endpoints for content categorization.
- name: YouTube
description: >-
YouTube creator data endpoints including basic metrics, historical data,
and detailed analytics.
paths:
/instagram/audience:
post:
tags:
- Instagram
summary: Get Audience Demographics
description: >-
Retrieve audience demographic insights for a specified Instagram
creator, including country distribution, gender breakdown, and age
composition. This endpoint provides detailed audience analytics to help
understand creator reach, evaluate audience alignment, and support
data‑driven influencer selection and campaign targeting.
Optionally pass `fields` in the request body to return only a subset
of demographic fields. You are billed for the fields you request, capped
at the full-bundle price. Fractional calls must be enabled on your API
key. Otherwise, a request that includes `fields` returns a `400` error
(`FractionalCallsNotEnabled`). Per-field costs are not published yet.
For how fractional calls work, see [Fractional
Calls](/api-v3/fractional-calls).
operationId: getInstagramAudience
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- uniqueId
properties:
uniqueId:
type: string
description: >-
Instagram account ID. Accepts `instagram` or `@instagram`
format (@ is stripped automatically).
pattern: ^@?[a-zA-Z0-9._]+$
minLength: 1
maxLength: 31
examples:
- instagram
fields:
type: array
description: >-
Subset of demographic fields to return. Omit or pass an
empty array to return the full response at the full-bundle
price. Per-field costs are not published yet.
items:
type: string
responses:
'200':
description: Instagram audience demographic data returned successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: >-
Returned audience demographic data of the specified
Instagram account.
properties:
audienceLocations:
type: array
description: >-
Country locations of the audience, sorted by
descending share.
examples:
- - country: TWN
share: 0.6521
- country: USA
share: 0.0813
- country: HKG
share: 0.0501
items:
type: object
description: Country distribution of the audience.
properties:
country:
type: string
description: >-
The country in **ISO 3166-1 alpha-3** format.
For details, see [Country
Codes](http://docs.creatordb.app/api-v2/country-code).
examples:
- TWN
share:
type: number
description: >-
Proportion of audience from that country,
rounded to 4th decimal place.
examples:
- 0.6521
required:
- country
- share
audienceGender:
type: object
description: Gender distribution of the audience.
properties:
maleRatio:
type: number
description: >-
Proportion of male audience, rounded to 4th
decimal place.
examples:
- 0.3233
femaleRatio:
type: number
description: >-
Proportion of female audience, rounded to 4th
decimal place.
examples:
- 0.6412
required:
- maleRatio
- femaleRatio
examples:
- maleRatio: 0.3233
femaleRatio: 0.6412
audienceAvgAge:
type: integer
description: Average age of the audience, rounded to an integer.
examples:
- 28
audienceAgeBreakdown:
type: array
description: Distribution of the audience by age range.
examples:
- - ageRange: 13-17
share: 0.0523
- ageRange: 18-24
share: 0.2871
- ageRange: 25-34
share: 0.3418
- ageRange: 35-44
share: 0.1825
- ageRange: 45-54
share: 0.0898
- ageRange: 55-64
share: 0.0312
- ageRange: 65+
share: 0.0153
items:
type: object
description: Age range distribution of the audience.
properties:
ageRange:
type: string
enum:
- 13-17
- 18-24
- 25-34
- 35-44
- 45-54
- 55-64
- 65+
description: >-
Age group.
Accepted values: `13-17`,
`18-24`, `25-34`, `35-44`, `45-54`, `55-64`,
`65+`
examples:
- 25-34
share:
type: number
description: >-
Percentage of audience in a specific age group,
rounded to 4th decimal place.
examples:
- 0.0523
required:
- ageRange
- share
required:
- audienceLocations
- audienceGender
- audienceAvgAge
- audienceAgeBreakdown
creditsUsed:
type: integer
description: Number of API credits consumed by this request.
examples:
- 1
creditsAvailable:
type: integer
description: Number of API credits remaining.
examples:
- -1
traceId:
type: string
description: Unique trace ID for each request.
examples:
- f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0
timestamp:
type: integer
description: >-
Time the response was generated, represented as a Unix
timestamp in milliseconds.
examples:
- 1750732453635
errorCode:
type: string
description: >-
Error code returned if the request fails. Empty if the
request is successful.
examples:
- ''
errorDescription:
type: string
description: >-
Description of the error. Empty if the request is
successful.
examples:
- ''
success:
type: boolean
description: '`true` if the request is successful.'
examples:
- true
required:
- data
- traceId
- timestamp
- errorCode
- errorDescription
- success
- creditsUsed
- creditsAvailable
examples:
default:
value:
data:
audienceLocations:
- country: USA
share: 0.7377
- country: GBR
share: 0.0493
- country: CAN
share: 0.0409
audienceGender:
maleRatio: 0.7752
femaleRatio: 0.2248
audienceAvgAge: 29
audienceAgeBreakdown:
- ageRange: 13-17
share: 0.1059
- ageRange: 18-24
share: 0.3429
- ageRange: 25-34
share: 0.313
- ageRange: 35-44
share: 0.1506
- ageRange: 45-54
share: 0.0572
- ageRange: 55-64
share: 0.0183
- ageRange: 65+
share: 0.0121
creditsUsed: 1
creditsAvailable: -1
traceId: 85dab7361bacc5adc50b6d9e991d528a
timestamp: 1768486538433
errorCode: ''
errorDescription: ''
success: true
'400':
description: Validation error.
content:
application/json:
schema:
type: object
title: ValidationErrorResponse
properties:
success:
const: false
error:
type: string
message:
type: string
timestamp:
type: integer
required:
- success
- error
- message
- timestamp
examples:
missing uniqueId:
summary: Missing uniqueId
value:
success: false
error: VALIDATION_ERROR
message: 'Missing required field: ''uniqueId''.'
timestamp: 1770099403116
invalid uniqueId:
summary: Invalid uniqueId format
value:
success: false
error: VALIDATION_ERROR
message: >-
Invalid 'uniqueId' format. Instagram unique ID must be
between 1 and 31 characters.
timestamp: 1770099403116
'429':
description: Exceeded quota or rate limit.
content:
application/json:
schema:
type: object
title: QuotaErrorResponse
properties:
success:
const: false
error:
type: string
message:
type: string
remainingPlanCredit:
type: number
required:
- success
- error
- message
- remainingPlanCredit
examples:
rate limit:
summary: Rate limit exceeded
value:
success: false
error: RATE_LIMIT_EXCEEDED
message: Too many requests. Please try again later.
quota exceeded:
summary: Credit quota exceeded
value:
success: false
error: QUOTA_EXCEEDED
message: Not enough credits to complete this request.
security:
- ApiKeyAuth: []
servers:
- url: https://apiv3.creatordb.app
description: Production Environment (CreatorDB Headless API V3)
x-codeSamples:
- lang: bash
label: cURL
source: |
curl -X POST "https://apiv3.creatordb.app/instagram/audience" \
-H "Content-Type: application/json" \
-H "api-key: " \
-d '{ "uniqueId": "cristiano" }'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
description: The valid CreatorDB API key for authentication.
name: api-key
in: header
````