> ## Documentation Index > Fetch the complete documentation index at: https://docs.upriver.ai/llms.txt > Use this file to discover all available pages before exploring further. # Personas (v3) > Get detailed audience personas for a brand. **Input:** Brand URL, optional query and effort level. **Output:** Personas with purchase triggers, barriers, behaviors, language patterns, and optional real world citations. ## OpenAPI ````yaml /api-reference/openapi.json post /v3/audience_insights openapi: 3.1.0 info: title: Upriver API description: >- 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. version: 1.0.0 servers: - url: https://api.upriver.ai description: Production API server security: [] tags: - name: Brands - name: Products - name: Creators - name: Audience - name: Sponsorships - name: Trends - name: Breakout Topics - name: Taxonomy paths: /v3/audience_insights: post: tags: - Audience summary: Personas (v3) description: >- Get detailed audience personas for a brand. **Input:** Brand URL, optional query and effort level. **Output:** Personas with purchase triggers, barriers, behaviors, language patterns, and optional real world citations. operationId: audience_insights_v3 requestBody: content: application/json: schema: $ref: '#/components/schemas/GroundedInsightsInput' required: true responses: '200': description: Audience personas content: application/json: schema: $ref: '#/components/schemas/AudienceInsightsResponseV3' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: GroundedInsightsInput: properties: brand_url: type: string title: Brand Url description: Brand website to research. examples: - https://nike.com query: anyOf: - type: string - type: 'null' title: Query description: >- Optional query to focus the audience research on a specific topic or angle. When provided, personas will be weighted toward conversations matching this query in addition to the brand itself. For example, 'running shoes for beginners' produces personas focused on entry-level runners, while 'streetwear fashion' emphasizes style-driven audiences. When omitted, the endpoint explores the brand broadly. effort: $ref: '#/components/schemas/GroundedEffort' description: 'Effort level: low, mid, high. Default is mid.' default: auto include_citations: type: boolean title: Include Citations description: When true, include real world citations for each persona. default: true type: object required: - brand_url title: GroundedInsightsInput AudienceInsightsResponseV3: properties: rollup_summary: anyOf: - type: string - type: 'null' title: Rollup Summary description: One-paragraph cross-persona summary (1-2 sentences). personas: items: $ref: '#/components/schemas/PersonaV3' type: array title: Personas description: 3-8 distinct audience personas. meta: $ref: '#/components/schemas/ResponseMetaV3' description: Generation metadata. type: object required: - personas title: AudienceInsightsResponseV3 HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError GroundedEffort: type: string enum: - auto - low - mid - high title: GroundedEffort PersonaV3: properties: label: type: string title: Label description: Short descriptive label for this audience segment. description: type: string title: Description description: 1-sentence summary of what was observed about this group. personality_traits: items: $ref: '#/components/schemas/PersonalityTraitV3' type: array title: Personality Traits description: >- Deprecated. Previously contained personality taxonomy traits. Now always empty — use buying_mindset for behavioral insights. deprecated: true buying_mindset: items: type: string type: array title: Buying Mindset description: >- 1-2 short observations about how this group makes buying decisions — what influences them, how they relate to brands. purchase_motivations: items: type: string type: array title: Purchase Motivations description: >- Why this group wants the product category — enduring desired outcomes, problems solved, and identity payoffs observed in real discussions. 3-5 items. purchase_triggers: items: type: string type: array title: Purchase Triggers description: >- What pushes them toward purchase now — specific moments, comparisons, and need states observed in real discussions. 3-5 items. purchase_barriers: items: type: string type: array title: Purchase Barriers description: >- What stops them from buying — specific fears, concerns, objections, and friction points observed in real discussions. 3-5 items. behaviors: items: type: string type: array title: Behaviors description: >- Deprecated. No longer populated — always returns an empty list. For behavioral insights use buying_mindset, purchase_triggers, and phrase_examples. deprecated: true phrase_examples: items: type: string type: array title: Phrase Examples description: >- Distinctive slang, idioms, jargon, emojis, hashtags — 1-5 words each. 3-7 items. voice_and_tone: items: type: string type: array title: Voice And Tone description: >- Deprecated. No longer populated — always returns an empty list. Use phrase_examples for how this audience communicates. deprecated: true communities: anyOf: - items: type: string type: array - type: 'null' title: Communities description: >- Online communities where this audience segment is most active, e.g. ['r/nutrition', 'r/Microbiome']. citations: items: $ref: '#/components/schemas/PersonaCitationV3' type: array title: Citations description: >- Supporting citations from real discussions that validate this segment's characteristics. type: object required: - label - description - purchase_motivations - purchase_triggers - purchase_barriers - phrase_examples title: PersonaV3 ResponseMetaV3: properties: generated_at: type: string title: Generated At type: object title: ResponseMetaV3 ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError PersonalityTraitV3: properties: id: type: string title: Id description: Taxonomy key, e.g. 'analytical', 'security_oriented'. label: type: string title: Label description: >- Human-readable label for the trait, e.g. 'Analytical', 'Stability-Seeking'. type: object required: - id - label title: PersonalityTraitV3 PersonaCitationV3: properties: title: type: string title: Title description: Title text: type: string title: Text description: Relevant excerpt from the citation url: anyOf: - type: string - type: 'null' title: Url description: URL of the source if available subreddit: anyOf: - type: string - type: 'null' title: Subreddit description: Subreddit if from Reddit type: object required: - title - text title: PersonaCitationV3 securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ````