Audience

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)

POST

audience_dimensions

Dimensions

curl --request POST \
  --url https://api.upriver.ai/v1/audience_dimensions \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "brand_url": "<string>",
  "response_config": {
    "include_rollup": false,
    "verbosity": "standard",
    "metadata_mode": "basic",
    "max_results": 5,
    "min_confidence": 0.55,
    "max_facts": 25,
    "min_fact_confidence": 0.3,
    "include_evidence_snippets": true,
    "max_snippets_per_fact": 3
  }
}
'

{
  "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>"
        }
      ]
    },
    "sources_analyzed": [
      "<string>"
    ],
    "content_analyzed_count": 0,
    "pipeline_version": "<string>"
  },
  "brand_name": "<string>",
  "facts": [
    {
      "fact": "<string>",
      "confidence": 0.5,
      "source_count": 2,
      "example_sources": [
        "<string>"
      ],
      "tier": "long_tail",
      "evidence_snippets": [
        {
          "source_id": "<string>",
          "source": "<string>",
          "title": "<string>",
          "text_snippet": "<string>",
          "url": "<string>"
        }
      ]
    }
  ],
  "brand_url": "<string>"
}

Authorizations

X-API-Key

string

header

required

Body

application/json

Input model for audience dimensions extraction.

brand_url

string

required

Brand website URL to analyze

Examples:

"https://drinkolipop.com"

"https://nike.com"

response_config

AudienceDimensionsResponseConfig · object

Output configuration

Show child attributes

Response

Successful Response

Response model for audience dimensions extraction.

meta

AudienceDimensionsMeta · object

required

Metadata about sources analyzed

Show child attributes

brand_name

string

required

The brand that was analyzed

facts

AudienceFact · object[]

required

Granular audience facts derived from online discussions, sorted by confidence (highest first). Each fact captures a distinct audience behavior, preference, or characteristic.

Show child attributes

brand_url

string | null

Brand website URL if available

PersonasGet 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)

⌘I

Dimensions

curl --request POST \
  --url https://api.upriver.ai/v1/audience_dimensions \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "brand_url": "<string>",
  "response_config": {
    "include_rollup": false,
    "verbosity": "standard",
    "metadata_mode": "basic",
    "max_results": 5,
    "min_confidence": 0.55,
    "max_facts": 25,
    "min_fact_confidence": 0.3,
    "include_evidence_snippets": true,
    "max_snippets_per_fact": 3
  }
}
'

{
  "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>"
        }
      ]
    },
    "sources_analyzed": [
      "<string>"
    ],
    "content_analyzed_count": 0,
    "pipeline_version": "<string>"
  },
  "brand_name": "<string>",
  "facts": [
    {
      "fact": "<string>",
      "confidence": 0.5,
      "source_count": 2,
      "example_sources": [
        "<string>"
      ],
      "tier": "long_tail",
      "evidence_snippets": [
        {
          "source_id": "<string>",
          "source": "<string>",
          "title": "<string>",
          "text_snippet": "<string>",
          "url": "<string>"
        }
      ]
    }
  ],
  "brand_url": "<string>"
}