> ## 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. # Dimensions > Extract atomic audience dimensions for a brand. Dimensions are the building blocks of personas. Returns granular behavioral, motivational, and lifestyle dimensions about relevant audiences for a specified brand. Each fact can be used for matching with user profiles. **Verbosity** controls fact phrasing (applies only to the `fact` field): - `verbose`: Full sentences with subject (e.g., 'This audience seeks healthy recipes') - `standard` (default): Phrases without subject (e.g., 'seeks healthy recipes') - `compact`: Keywords only (e.g., 'healthy recipes') **Response includes:** - Audience dimensions with classification and confidence scores - Supporting evidence snippets (optional) ## OpenAPI ````yaml /api-reference/openapi.json post /v1/audience_dimensions 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: /v1/audience_dimensions: post: tags: - Audience summary: Dimensions description: >- Extract atomic audience dimensions for a brand. Dimensions are the building blocks of personas. Returns granular behavioral, motivational, and lifestyle dimensions about relevant audiences for a specified brand. Each fact can be used for matching with user profiles. **Verbosity** controls fact phrasing (applies only to the `fact` field): - `verbose`: Full sentences with subject (e.g., 'This audience seeks healthy recipes') - `standard` (default): Phrases without subject (e.g., 'seeks healthy recipes') - `compact`: Keywords only (e.g., 'healthy recipes') **Response includes:** - Audience dimensions with classification and confidence scores - Supporting evidence snippets (optional) operationId: audience_dimensions requestBody: content: application/json: schema: $ref: '#/components/schemas/AudienceDimensionsInput' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AudienceDimensionsResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: AudienceDimensionsInput: properties: brand_url: type: string title: Brand Url description: Brand website URL to analyze examples: - https://drinkolipop.com - https://nike.com response_config: $ref: '#/components/schemas/AudienceDimensionsResponseConfig' description: Output configuration type: object required: - brand_url title: AudienceDimensionsInput description: Input model for audience dimensions extraction. AudienceDimensionsResponse: properties: meta: $ref: '#/components/schemas/AudienceDimensionsMeta' description: Metadata about sources analyzed brand_name: type: string title: Brand Name description: The brand that was analyzed brand_url: anyOf: - type: string - type: 'null' title: Brand Url description: Brand website URL if available facts: items: $ref: '#/components/schemas/AudienceFact' type: array title: Facts description: >- Granular audience facts derived from online discussions, sorted by confidence (highest first). Each fact captures a distinct audience behavior, preference, or characteristic. type: object required: - meta - brand_name - facts title: AudienceDimensionsResponse description: Response model for audience dimensions extraction. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AudienceDimensionsResponseConfig: 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 max_facts: type: integer maximum: 50 minimum: 5 title: Max Facts description: Maximum number of audience facts to return (default 25) default: 25 min_fact_confidence: type: number maximum: 1 minimum: 0 title: Min Fact Confidence description: >- Minimum confidence threshold for facts. Facts with scores below this will be filtered out. default: 0.3 include_evidence_snippets: type: boolean title: Include Evidence Snippets description: Include text snippets from supporting Reddit posts default: true max_snippets_per_fact: type: integer maximum: 5 minimum: 1 title: Max Snippets Per Fact description: Maximum evidence snippets per fact (1-5) default: 3 type: object title: AudienceDimensionsResponseConfig description: Output configuration specific to /audience_dimensions. AudienceDimensionsMeta: 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) sources_analyzed: items: type: string type: array title: Sources Analyzed description: Communities that were analyzed content_analyzed_count: type: integer title: Content Analyzed Count description: Total number of discussions analyzed default: 0 pipeline_version: anyOf: - type: string - type: 'null' title: Pipeline Version hidden: true type: object required: - generated_at title: AudienceDimensionsMeta description: Extended metadata for audience dimensions response. AudienceFact: properties: fact: type: string title: Fact description: >- A concise statement about the target audience. Format depends on verbosity setting: verbose=full sentence with subject, standard=phrase without subject, compact=keywords only. examples: - This audience seeks healthier alternatives to sugary drinks - seeks healthier alternatives to sugary drinks - healthier alternatives to sugary drinks dimension: type: string enum: - behavior - motivation - lifestyle - concern - interest title: Dimension description: >- Category of the fact: 'behavior' = actions/habits, 'motivation' = why they buy/engage, 'lifestyle' = how they live, 'concern' = worries/pain points, 'interest' = topics they follow tier: type: string enum: - direct - contextual - long_tail title: Tier description: >- Relevance tier: 'direct' = brand mentions, competitors, product category; 'contextual' = shopping contexts, purchase-adjacent discussions; 'long_tail' = non-obvious audience segments (health conditions, lifestyles) default: long_tail confidence: type: number maximum: 1 minimum: 0 title: Confidence description: >- Confidence score based on evidence strength (0.0-1.0). Higher scores indicate more supporting evidence from online discussions. source_count: type: integer minimum: 1 title: Source Count description: Number of discussions supporting this fact example_sources: items: type: string type: array title: Example Sources description: Communities where this fact was observed evidence_snippets: items: $ref: '#/components/schemas/EvidenceSnippet' type: array maxItems: 3 title: Evidence Snippets description: Up to 3 supporting discussions with text excerpts type: object required: - fact - dimension - confidence - source_count - example_sources title: AudienceFact description: Single granular fact about brand-adjacent audience. 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. EvidenceSnippet: properties: source_id: type: string title: Source Id description: Unique identifier for the source content source: type: string title: Source description: Community or platform where this was found title: type: string title: Title description: Title of the discussion text_snippet: type: string title: Text Snippet description: Excerpt of relevant content (~200 chars) url: type: string title: Url description: URL to the source content type: object required: - source_id - source - title - text_snippet - url title: EvidenceSnippet description: Supporting evidence from online discussions. 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'. securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ````