> ## 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 > 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 token - `sync`: Include citations in response (slower) - `none`: No citations (fastest) ## OpenAPI ````yaml /api-reference/openapi.json post /v2/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: /v2/audience_insights: post: tags: - Audience summary: Personas description: >- 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 token - `sync`: Include citations in response (slower) - `none`: No citations (fastest) operationId: audience_insights_v2 requestBody: content: application/json: schema: $ref: '#/components/schemas/AudienceInsightsInput' required: true responses: '200': description: JSON object containing audience insights data content: application/json: schema: $ref: '#/components/schemas/AudienceInsightsResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' deprecated: true security: - APIKeyHeader: [] components: schemas: AudienceInsightsInput: properties: brief: type: string title: Brief description: Creative brief describing the brand, product, and/or campaign. brand: anyOf: - $ref: '#/components/schemas/Brand' - type: 'null' description: Brand context including name, voice, and values. industries: anyOf: - items: type: string type: array - type: 'null' title: Industries description: Industry categories to guide the search. product: anyOf: - $ref: '#/components/schemas/Product' - type: 'null' description: Product details for better targeting. products: anyOf: - items: $ref: '#/components/schemas/Product' type: array - type: 'null' title: Products description: Optional list of products to consider (top item treated as primary). audience: anyOf: - $ref: '#/components/schemas/Audience' - type: 'null' description: >- Target audience definition. Can be a simple string or structured object. scope: $ref: '#/components/schemas/ScopeConfig' description: >- Retrieval scope: time window, geographic markets, social platforms, content sources. response_config: $ref: '#/components/schemas/AudienceInsightsResponseConfig' description: Output configuration industry: anyOf: - type: string - type: 'null' title: Industry description: >- Singular industry (from /brand endpoint, auto-converted to industries array) type: object required: - brief title: AudienceInsightsInput example: 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 AudienceInsightsResponse: properties: meta: $ref: '#/components/schemas/ResponseMeta' description: >- Generation context and diagnostics (e.g., input echoes, model versions, timing, provenance flags). rollup_summary: anyOf: - type: string - type: 'null' title: Rollup Summary description: >- One-paragraph cross-persona summary (1-2 sentences). Optional; informational only. personas: items: $ref: '#/components/schemas/Persona' type: array title: Personas description: >- Primary and (optionally) recommended personas, each with full insight blocks. type: object required: - meta - personas title: AudienceInsightsResponse description: |- Persona-level audience insights for creative strategy. Each persona includes complete insight blocks; no global/override packs. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError Brand: properties: name: anyOf: - type: string - type: 'null' title: Name description: Brand name url: anyOf: - type: string - type: 'null' title: Url description: Brand website URL description: anyOf: - type: string - type: 'null' title: Description description: Concise summary of what the brand/company is and does voice: anyOf: - type: string - type: 'null' title: Voice description: Brand voice/tone (e.g., 'energetic, motivational, friendly') values: anyOf: - items: type: string type: array - type: 'null' title: Values description: >- Brand values (e.g., ['performance', 'self improvement', 'community']) tagline: anyOf: - type: string - type: 'null' title: Tagline description: Brand tagline or slogan mission: anyOf: - type: string - type: 'null' title: Mission description: Brand mission statement industry: anyOf: - type: string - type: 'null' title: Industry description: Primary industry or sector target_audience: anyOf: - type: string - type: 'null' title: Target Audience description: Primary target audience description identity: anyOf: - additionalProperties: true type: object - type: 'null' title: Identity description: Structured identity block captured from /brand research language: anyOf: - additionalProperties: true type: object - type: 'null' title: Language description: Structured brand language details (tone, key phrases) colors: anyOf: - additionalProperties: true type: object - type: 'null' title: Colors description: Brand color palette (primary, secondary, etc.) brand_name: anyOf: - type: string - type: 'null' title: Brand Name description: Alias for name brand_url: anyOf: - type: string - type: 'null' title: Brand Url description: Alias for url brand_identity: anyOf: - additionalProperties: true type: object - type: 'null' title: Brand Identity description: Nested brand identity object (automatically flattened) brand_colors: anyOf: - additionalProperties: true type: object - type: 'null' title: Brand Colors description: Alias for colors type: object title: Brand description: >- Brand-side context you'd include in a creative brief (not query filters). Product: properties: name: anyOf: - type: string - type: 'null' title: Name description: Product name url: anyOf: - type: string - type: 'null' title: Url description: Product page URL description: anyOf: - type: string - type: 'null' title: Description description: Product description category: anyOf: - type: string - type: 'null' title: Category description: Product category key_features: anyOf: - items: type: string type: array - type: 'null' title: Key Features description: Key features price_tier: anyOf: - type: string enum: - value - mid - premium - type: 'null' title: Price Tier description: Market price tier reason: anyOf: - type: string - type: 'null' title: Reason description: Evidence from /brand endpoint (automatically excluded from output) type: object title: Product Audience: properties: description: anyOf: - type: string - type: 'null' title: Description description: Narrative description of the audience (free-form). geo: anyOf: - items: type: string type: array - type: 'null' title: Geo description: >- List of ISO country/region codes to focus research on (e.g. ['US','CA']). age_range: anyOf: - type: string - type: 'null' title: Age Range description: Age band to narrow analysis (e.g. '18-24'). gender: anyOf: - type: string enum: - male - female - nonbinary - all - type: 'null' title: Gender description: Target gender. Optional; typically omitted unless narrowing scope. segments: anyOf: - items: type: string type: array - type: 'null' title: Segments description: >- Interest or psychographic tags to guide analysis (e.g. ['ingredient-obsessed','dupe-hunters']). language: anyOf: - type: string - type: 'null' title: Language description: Content language to analyze, as ISO code (e.g. 'en', 'zh'). locale: anyOf: - type: string - type: 'null' title: Locale description: Locale for cultural tone/formatting, BCP-47 code (e.g. 'en-US'). type: object title: Audience description: Audience can be provided as a plain string or as a structured object. ScopeConfig: properties: from_time: anyOf: - type: string - type: string format: date-time - type: 'null' title: From Time description: >- The start of the time window for the scan. This can be an absolute timestamp in ISO 8601 format (e.g., '2025-08-11T00:00:00Z'), or a relative duration string from the current time (e.g., '7d' for 7 days ago, '24h' for 24 hours ago, '2w' for 2 weeks ago). default: 90d to_time: anyOf: - type: string - type: string format: date-time - type: 'null' title: To Time description: >- The end of the time window for the scan. This can be the string 'now', an absolute timestamp in ISO 8601 format (e.g., '2025-08-11T00:00:00Z'), or a relative duration string from the current time (e.g., '24h' for 24 hours ago). A relative duration for `to_time` should be more recent than `from_time`. default: now platforms: anyOf: - items: type: string enum: - tiktok - instagram - youtube - twitch - reddit - x - discord - facebook - snapchat - pinterest - forums - blogs - reviews type: array - type: 'null' title: Platforms description: >- Platforms to scan and include in results (e.g., Reddit, blogs, forums) type: object title: ScopeConfig description: |- Where/when to look for signals and which platforms to use. These are query filters (not brand metadata). Time window: - Use 'from_time' (start) and 'to_time' (end). - Accepts ISO8601 UTC or relative durations like '7d', '24h', '2w'. - If only 'from_time' is relative, window is [now - duration, now]. - 'to_time' may be 'now' (default), ISO8601 UTC, or a relative duration interpreted as now - duration. - After normalization the service validates start < end. Platforms: - Use 'platforms' to specify which platforms to both scan AND return (e.g., reddit, blogs, forums). - This controls both the data sources analyzed and the results returned. AudienceInsightsResponseConfig: properties: include_rollup: type: boolean title: Include Rollup description: >- Include a single-paragraph rollup summarizing all results discovered in this response. default: false verbosity: type: string enum: - compact - standard - verbose title: Verbosity description: >- Controls optional fields/array lengths in the payload (compact | standard | verbose). default: standard metadata_mode: type: string enum: - none - basic - debug title: Metadata Mode description: >- Response metadata level: 'none' = omit counts/source_filters/debug_info; 'basic' = include counts + source_filters; 'debug' = include counts + source_filters + debug_info. default: basic max_results: type: integer maximum: 50 minimum: 1 title: Max Results description: Upper bound on results returned (post-filter). default: 5 min_confidence: anyOf: - type: number maximum: 1 minimum: 0 - type: 'null' title: Min Confidence description: Drop results below this confidence score. default: 0.55 citations_mode: type: string enum: - sync - async - none title: Citations Mode description: >- Controls how citations are handled: - 'sync': Generates citations inline and includes them in the main response (slower, but complete in one call) - 'async': Returns personas immediately with a continuation_token, fetch citations separately via GET /audience_insights/{token}/citations (faster initial response) - 'none': Omits citations entirely (fastest, no continuation_token) default: async include_recommended: type: boolean title: Include Recommended description: >- When true, return adjacent/recommended personas in addition to the primary (if any). default: false include_citations: type: boolean title: Include Citations description: >- When true, include supporting citations from real discussions for each persona. default: true max_citations_per_persona: type: integer maximum: 10 minimum: 1 title: Max Citations Per Persona description: >- Maximum number of citations to include per persona when include_citations is true. default: 5 min_citation_score: type: number maximum: 1 minimum: 0 title: Min Citation Score description: >- Minimum relevance score threshold for citations. Citations with scores below this will be filtered out. default: 0.6 cache_citations: type: boolean title: Cache Citations description: >- When true, cache the complete response including citations. When false, citations are fetched fresh on every request (LLM response is still cached). default: true include_supporting_evidence: type: boolean title: Include Supporting Evidence description: >- When true, include real supporting evidence from Reddit, YouTube, and Amazon that demonstrates each persona's behavioral traits. default: true type: object title: AudienceInsightsResponseConfig description: >- Output configuration specific to /audience_insights. Inherit generic fields from ResponseConfig (e.g., min_confidence, max_items). ResponseMeta: properties: generated_at: type: string format: date-time title: Generated At description: UTC timestamp when this response was generated industries: anyOf: - items: type: string type: array - type: 'null' title: Industries description: Resolved industry labels, when applicable continuation_token: anyOf: - type: string - type: 'null' title: Continuation Token description: A token to retrieve the next part of the result (e.g., citations). counts: anyOf: - $ref: '#/components/schemas/ResponseCounts' - type: 'null' description: Item counts and scope breakdown (basic and debug modes) source_filters: anyOf: - $ref: '#/components/schemas/SourceFilters' - type: 'null' description: Applied source filters (basic and debug modes) debug_info: anyOf: - $ref: '#/components/schemas/DebugInfo' - type: 'null' description: Development diagnostics (debug mode only) type: object required: - generated_at title: ResponseMeta description: |- Response-level metadata (flat and endpoint-agnostic). Provenance (always present): - generated_at, time_window, industries Diagnostics (gated by metadata_mode): - counts: ResponseCounts [included when metadata_mode in {'basic','debug'}] - source_filters: SourceFilters [included when metadata_mode in {'basic','debug'}] - debug_info: DebugInfo [included when metadata_mode == 'debug'] Notes: - 'counts.total' SHOULD equal the length of this endpoint's primary items array. - 'by_scope' counts are based on ContentScope classification of returned items. - ContentScope is about applicability (output classification), not where data was sourced. Persona: properties: label: type: string title: Label description: >- Short, descriptive label for this audience segment (e.g., 'Fitness Enthusiasts', 'Tech Professionals'). description: type: string title: Description description: 1-sentence summary of this persona. personality_traits: items: $ref: '#/components/schemas/PersonalityTrait' type: array title: Personality Traits description: >- A list of the 2-3 most prominent personality traits for this persona. psychology: $ref: '#/components/schemas/Psychology' description: >- What motivates this audience, what holds them back, and when they're most receptive to messaging. language_patterns: anyOf: - $ref: '#/components/schemas/LanguagePatterns' - type: 'null' description: Observed language use patterns within this audience segment. supporting_evidence: anyOf: - $ref: '#/components/schemas/SupportingEvidence' - type: 'null' description: >- Real-world examples with valid URLs showing how this persona expresses themselves on different platforms (Reddit, YouTube, Amazon). Retrieved via search after persona generation. citations: items: $ref: '#/components/schemas/PersonaCitation' type: array title: Citations description: >- Supporting citations from real discussions that validate this persona's characteristics. behaviors_demonstrated: items: type: string type: array title: Behaviors Demonstrated description: >- Deduped list of key behaviors, attitudes, and psychological patterns demonstrated across the citation evidence for this persona. type: object required: - label - description - personality_traits - psychology title: Persona description: >- An audience segment with complete, persona-scoped guidance for creative generation. Flat structure: all insight blocks live on the persona (no global/override packs). 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 ResponseCounts: properties: total: type: integer title: Total description: Total number of items in the response (e.g., len(trends)). by_scope: $ref: '#/components/schemas/ContentScopeCounts' description: Breakdown by ContentScope for the returned items. type: object required: - total - by_scope title: ResponseCounts description: >- Top-level count diagnostics for the response payload. - 'total' MUST equal the number of items returned in this endpoint's main list. - 'by_scope' breaks down that same set by ContentScope. SourceFilters: properties: platforms: anyOf: - items: type: string type: array - type: 'null' title: Platforms source_names: anyOf: - items: type: string type: array - type: 'null' title: Source Names source_urls: anyOf: - items: type: string maxLength: 2083 minLength: 1 format: uri type: array - type: 'null' title: Source Urls restriction: type: string enum: - none - prioritize - only title: Restriction default: none type: object title: SourceFilters DebugInfo: properties: duration_ms: type: integer title: Duration Ms description: End-to-end processing time for this request (ms). candidates_before_filter: type: integer title: Candidates Before Filter description: >- Number of candidate items BEFORE applying min_confidence/max_results. applied_filters: items: $ref: '#/components/schemas/AppliedFilter' type: array title: Applied Filters description: List of filters/normalizations that materially changed the payload. type: object required: - duration_ms - candidates_before_filter title: DebugInfo description: |- Optional development diagnostics (included when metadata_mode='debug'). Times and counts should refer to the current request execution only. PersonalityTrait: properties: trait: type: string title: Trait description: >- The specific trait value from the spectrum (e.g., 'Analytical' or 'Intuitive'). Must be either the 'low' or 'high' value from the trait's spectrum. justification: type: string title: Justification description: A brief justification for why this trait value was selected. type: object required: - trait - justification title: PersonalityTrait description: Represents a single personality trait from the taxonomy spectrum. Psychology: properties: motivations: items: type: string type: array title: Motivations description: Top reasons this audience would be interested, ranked by importance. barriers: items: type: string type: array title: Barriers description: Top reasons this audience might hesitate, ranked by importance. triggers: items: type: string type: array title: Triggers description: Times when this audience is most receptive to your message. type: object required: - motivations - barriers - triggers title: Psychology description: What motivates this audience and what holds them back. LanguagePatterns: properties: common_phrases: items: type: string type: array title: Common Phrases description: Frequently used words, slang, hashtags, and recurring expressions. stylistic_features: items: type: string type: array title: Stylistic Features description: >- Observable style markers: sentence length, punctuation, emoji usage, formatting habits. tone_descriptors: items: type: string type: array title: Tone Descriptors description: >- Descriptors of the overall tone: informal, sarcastic, supportive, hype-driven, etc. type: object required: - common_phrases - stylistic_features - tone_descriptors title: LanguagePatterns description: Observed language use within this audience segment. SupportingEvidence: properties: reddit_posts: items: $ref: '#/components/schemas/RedditEvidence' type: array title: Reddit Posts description: >- List of 3-5 Reddit posts/comments that demonstrate this persona's behavioral traits, each with a summary and justification type: object required: - reddit_posts title: SupportingEvidence description: |- Real-world Reddit evidence showing the persona's behavioral traits in action, with LLM justifications. PersonaCitation: properties: title: type: string title: Title description: Title of the cited content 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 relevance_score: type: number title: Relevance Score description: Relevance score from vector search reason: type: string title: Reason description: Succinct reason explaining why this citation supports the persona source: anyOf: - type: string - type: 'null' title: Source description: >- Source method used to find this citation. Only included in responses when metadata_mode is 'debug'. type: object required: - title - text - relevance_score - reason title: PersonaCitation description: A citation supporting persona insights. ContentScopeCounts: properties: general: type: integer title: General default: 0 multi_platform: type: integer title: Multi Platform default: 0 platform_specific: type: integer title: Platform Specific default: 0 type: object title: ContentScopeCounts description: |- Count of returned items by ContentScope. These counts reflect the final payload after confidence/limit filters. AppliedFilter: properties: name: type: string title: Name description: Filter key, e.g., 'time_range', 'platforms', 'min_confidence'. value: title: Value description: Applied value (JSON-serializable). reason: anyOf: - type: string - type: 'null' title: Reason description: Optional note (e.g., 'filled default', 'normalized'). type: object required: - name - value title: AppliedFilter description: >- Structured record of a filter or normalization that affected the returned payload. Good for audit/debug; suitable for 'metadata_mode=debug'. RedditEvidence: properties: title: type: string title: Title description: Title of the Reddit post summary: type: string title: Summary description: >- AI-generated summary of the Reddit discussion that captures the core message and sentiment url: type: string title: Url description: Valid URL to the Reddit post or comment subreddit: anyOf: - type: string - type: 'null' title: Subreddit description: Subreddit where this was posted justification: type: string title: Justification description: >- LLM-generated explanation of why this specific post supports the persona's behavioral traits and psychology type: object required: - title - summary - url - justification title: RedditEvidence description: Individual Reddit post/comment supporting a persona. securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ````