A social insights API for ad generation platforms. It provides structured signals, like psychographics, behavioral insights, trends, and audience language, to help AI models generate relevant, higher-converting ads.
Get detailed audience personas with psychographics, behaviors, motivators, and barriers. Ideal for creative strategy, targeting, and understanding your audience at a psychological level.
Input: Provide brand info, products, and industry context. Can chain output from Brand Research endpoint.
Output: 3-5 distinct personas with personality traits, behavioral patterns, motivations, and barriers.
Citations Mode:
async (recommended): Fast response, fetch citations separately via continuation tokensync: Include citations in response (slower)none: No citations (fastest)Creative brief describing the brand, product, and/or campaign.
Brand context including name, voice, and values.
Industry categories to guide the search.
Product details for better targeting.
Optional list of products to consider (top item treated as primary).
Target audience definition. Can be a simple string or structured object.
Retrieval scope: time window, geographic markets, social platforms, content sources.
Output configuration
Singular industry (from /brand endpoint, auto-converted to industries array)
curl https://api.upriver.ai/v2/audience_insights \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-API-Key: YOUR_SECRET_TOKEN' \
--data '{
"brief": "headphones for gen z runners, waterproof, good bass, long battery",
"industries": [
"consumer electronics",
"fitness"
],
"brand": {
"voice": "energetic, motivational, friendly",
"values": [
"performance",
"self improvement",
"community"
]
},
"product": {
"category": "headphones",
"price_tier": "mid"
},
"audience": {
"age_range": "18-24"
}
}'
{
"meta": {
"generated_at": "2026-09-05T06:49:26.587Z",
"industries": [
"string"
],
"continuation_token": "string",
"counts": {
"total": 1,
"by_scope": {
"general": 0,
"multi_platform": 0,
"platform_specific": 0
}
},
"source_filters": {
"platforms": [
"string"
],
"source_names": [
"string"
],
"source_urls": [
"https://example.com"
],
"restriction": "none"
},
"debug_info": {
"duration_ms": 1,
"candidates_before_filter": 1,
"applied_filters": [
{
"name": "string",
"value": null,
"reason": "string"
}
]
}
},
"rollup_summary": "string",
"personas": [
{
"label": "string",
"description": "string",
"personality_traits": [
{
"trait": "string",
"justification": "string"
}
],
"psychology": {
"motivations": [
"string"
],
"barriers": [
"string"
],
"triggers": [
"string"
]
},
"language_patterns": {
"common_phrases": [
"string"
],
"stylistic_features": [
"string"
],
"tone_descriptors": [
"string"
]
},
"supporting_evidence": {
"reddit_posts": [
{
"title": "string",
"summary": "string",
"url": "string",
"subreddit": "string",
"justification": "string"
}
]
},
"citations": [
{
"title": "string",
"text": "string",
"url": "string",
"subreddit": "string",
"relevance_score": 1,
"reason": "string",
"source": "string"
}
],
"behaviors_demonstrated": [
"string"
]
}
]
}