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
/
v1
/
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
}
}
'import requests
url = "https://api.upriver.ai/v1/audience_dimensions"
payload = {
"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
}
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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
}
})
};
fetch('https://api.upriver.ai/v1/audience_dimensions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.upriver.ai/v1/audience_dimensions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.upriver.ai/v1/audience_dimensions"
payload := strings.NewReader("{\n \"brand_url\": \"<string>\",\n \"response_config\": {\n \"include_rollup\": false,\n \"verbosity\": \"standard\",\n \"metadata_mode\": \"basic\",\n \"max_results\": 5,\n \"min_confidence\": 0.55,\n \"max_facts\": 25,\n \"min_fact_confidence\": 0.3,\n \"include_evidence_snippets\": true,\n \"max_snippets_per_fact\": 3\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.upriver.ai/v1/audience_dimensions")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"brand_url\": \"<string>\",\n \"response_config\": {\n \"include_rollup\": false,\n \"verbosity\": \"standard\",\n \"metadata_mode\": \"basic\",\n \"max_results\": 5,\n \"min_confidence\": 0.55,\n \"max_facts\": 25,\n \"min_fact_confidence\": 0.3,\n \"include_evidence_snippets\": true,\n \"max_snippets_per_fact\": 3\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.upriver.ai/v1/audience_dimensions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"brand_url\": \"<string>\",\n \"response_config\": {\n \"include_rollup\": false,\n \"verbosity\": \"standard\",\n \"metadata_mode\": \"basic\",\n \"max_results\": 5,\n \"min_confidence\": 0.55,\n \"max_facts\": 25,\n \"min_fact_confidence\": 0.3,\n \"include_evidence_snippets\": true,\n \"max_snippets_per_fact\": 3\n }\n}"
response = http.request(request)
puts response.read_body{
"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>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Authorizations
Body
application/json
Response
Successful Response
Response model for audience dimensions extraction.
Metadata about sources analyzed
Show child attributes
Show child attributes
The brand that was analyzed
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
Show child attributes
Brand website URL if available
⌘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
}
}
'import requests
url = "https://api.upriver.ai/v1/audience_dimensions"
payload = {
"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
}
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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
}
})
};
fetch('https://api.upriver.ai/v1/audience_dimensions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.upriver.ai/v1/audience_dimensions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.upriver.ai/v1/audience_dimensions"
payload := strings.NewReader("{\n \"brand_url\": \"<string>\",\n \"response_config\": {\n \"include_rollup\": false,\n \"verbosity\": \"standard\",\n \"metadata_mode\": \"basic\",\n \"max_results\": 5,\n \"min_confidence\": 0.55,\n \"max_facts\": 25,\n \"min_fact_confidence\": 0.3,\n \"include_evidence_snippets\": true,\n \"max_snippets_per_fact\": 3\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.upriver.ai/v1/audience_dimensions")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"brand_url\": \"<string>\",\n \"response_config\": {\n \"include_rollup\": false,\n \"verbosity\": \"standard\",\n \"metadata_mode\": \"basic\",\n \"max_results\": 5,\n \"min_confidence\": 0.55,\n \"max_facts\": 25,\n \"min_fact_confidence\": 0.3,\n \"include_evidence_snippets\": true,\n \"max_snippets_per_fact\": 3\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.upriver.ai/v1/audience_dimensions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"brand_url\": \"<string>\",\n \"response_config\": {\n \"include_rollup\": false,\n \"verbosity\": \"standard\",\n \"metadata_mode\": \"basic\",\n \"max_results\": 5,\n \"min_confidence\": 0.55,\n \"max_facts\": 25,\n \"min_fact_confidence\": 0.3,\n \"include_evidence_snippets\": true,\n \"max_snippets_per_fact\": 3\n }\n}"
response = http.request(request)
puts response.read_body{
"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>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}