Skip to main content
POST
/
v2
/
audience_insights
Insights
curl --request POST \
  --url https://api.upriver.ai/v2/audience_insights \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --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": "2023-11-07T05:31:56Z",
    "industries": [
      "<string>"
    ],
    "continuation_token": "<string>",
    "counts": {
      "total": 123,
      "by_scope": {
        "general": 0,
        "multi_platform": 0,
        "platform_specific": 0
      }
    },
    "source_filters": {
      "platforms": [
        "<string>"
      ],
      "source_names": [
        "<string>"
      ],
      "source_urls": [
        "<string>"
      ],
      "restriction": "none"
    },
    "debug_info": {
      "duration_ms": 123,
      "candidates_before_filter": 123,
      "applied_filters": [
        {
          "name": "<string>",
          "value": "<unknown>",
          "reason": "<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>",
            "justification": "<string>",
            "subreddit": "<string>"
          }
        ]
      },
      "citations": [
        {
          "title": "<string>",
          "text": "<string>",
          "relevance_score": 123,
          "reason": "<string>",
          "url": "<string>",
          "subreddit": "<string>",
          "source": "<string>"
        }
      ],
      "behaviors_demonstrated": [
        "<string>"
      ]
    }
  ],
  "rollup_summary": "<string>"
}

Authorizations

​
X-API-Key
string
header
required

Body

application/json
​
brief
string
required

Creative brief describing the brand, product, and/or campaign.

​
brand
Brand · object

Brand context including name, voice, and values.

​
industries
string[] | null

Industry categories to guide the search.

​
product
Product · object

Product details for better targeting.

​
products
Product · object[] | null

Optional list of products to consider (top item treated as primary).

​
audience
Audience · object

Target audience definition. Can be a simple string or structured object.

​
scope
ScopeConfig · object

Retrieval scope: time window, geographic markets, social platforms, content sources.

​
response_config
AudienceInsightsResponseConfig · object

Output configuration

​
model_variant
string | null

The model variant to use for generating insights. Defaults to the API's primary model if not set.

Example:

"grok-4"

​
industry
string | null

Singular industry (from /brand endpoint, auto-converted to industries array)

Response

JSON object containing audience insights data

Persona-level audience insights for creative strategy. Each persona includes complete insight blocks; no global/override packs.

​
meta
ResponseMeta · object
required

Generation context and diagnostics (e.g., input echoes, model versions, timing, provenance flags).

​
personas
Persona · object[]
required

Primary and (optionally) recommended personas, each with full insight blocks.

​
rollup_summary
string | null

One-paragraph cross-persona summary (1-2 sentences). Optional; informational only.