buzzabout docsAudience profiles
POST /v1/audience_profiles — global, filterable, paginated profiles across one or more audience datasets.
The audience-profiles endpoint is global: one call returns
profiles from every audience dataset owned by the calling account.
Pass audience_dataset_ids to scope; omit it to span everything.
This is a POST (not GET) because filters are non-trivially nested,
mirroring the POST /v1/mentions shape.
Pricing
Free — no credits charged. The cost lives on the upstream audience-dataset run that collected the profiles. See Pricing.
Endpoint
Authorization
ApiKeyAuth Buzzabout API key, beginning with bz_live_ (or bz_test_ for staging-only keys).
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
curl -X POST "https://example.com/v1/audience_profiles" \ -H "Content-Type: application/json" \ -d '{ "audience_dataset_ids": [ "ad_2N9CnZSjLZA8ZkFqA6E1bKpY7Wj" ], "filters": { "age": { "in": [ "25-34", "35-44" ] }, "gender": { "in": [ "male" ] } }, "limit": 20, "order": "desc", "sort": "date" }'{
"status": "info",
"data": [
{
"id": "string",
"run_id": "string",
"source": "reddit",
"username": "string",
"display_name": "string",
"avatar": {
"type": "image",
"version_list": [
{
"url": "string",
"width": 0,
"height": 0
}
],
"description": ""
},
"bio": "string",
"external_link": "string",
"is_verified": true,
"follower_count": 0,
"following_count": 0,
"content_count": 0,
"engagement_rate": 0,
"posting_cadence": "string",
"creator_tier": "string",
"location_country": "string",
"location_city": "string",
"primary_language": "string",
"authenticity_score": 0,
"authenticity_reason": "string",
"aesthetic": "string",
"communication_tone": "string",
"content_niche": [
"string"
],
"interest_clusters": [
"string"
],
"brand_affinities": [
"string"
],
"occupation": "string",
"industry": "string",
"ocean": {},
"summary": "string",
"score": 0,
"platform_metadata": {},
"created_at": 0
}
],
"has_next": true,
"cursor": "string"
}{
"status": "info",
"error_code": "audience_dataset_not_found",
"detail": "string",
"transient": true
}{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string"
}
]
}Filters
filters carries the same OR-of-AND-groups shape as
mentions. Available filter types
for profiles cover age range, location, role, interests, and inferred
persona — the schema above enumerates the exact union.
Maximum 10 filters total across all groups.
Sort fields
sort accepts: created_at, audience_dataset_run_at. Other
dimensions (engagement-style metrics) are deliberately absent —
profiles do not carry their own engagement counts.
Cursors
Cursors encode the sort dimension. Switch sort between calls →
fetch a fresh page (don't reuse a cursor across sorts).
Next steps
- Audience datasets — manage the containers profiles live in.
- Mentions — the posts that gave rise to these profiles.