> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Sentiment
Per-brand sentiment as percentages from either AI responses or the pages those
responses cite. `asset` is **required** because sentiment is calculated for one
brand at a time.
* **`source: "response"`** (default): sentiment in AI responses. Metrics are
`positive_sentiment`, `negative_sentiment`, and opt-in `occurrence`.
* **`source: "citation"`**: one row per cited page, with
`positive_sentiment`, `negative_sentiment`, and model-balanced
`citation_share`. It defaults to sorting by `citation_share`; explicitly set
`sort.field` to `positive_sentiment` to sort by page sentiment instead.
* **Comparison dates:** add `comparison_start_date` and `comparison_end_date`.
Response rows include previous sentiment metrics. Citation rows include the
page's previous `citation_share`.
Response sentiment supports up to two `group_by` dimensions from `topic`,
`region`, `model`, `prompt`, `persona`, `tag`, `theme`, `claim`, `run`, and
`competitor`, plus `date`. Citation sentiment is page-only and rejects
`group_by`; use filters to narrow the page population.
Both sources accept prompt-layer filters such as `model`, `topic`, `region`,
`persona`, `prompt`, and `tag`, plus top-level `theme` / `claim` filters. Citation
sentiment additionally accepts these top-level filters:
* `citation_category`: `is` or `in`. Values can be built-in categories
(`owned`, `competition`, `social`, `earned_media`, `earned_institutions`,
`pr_wire`, `other`) or a custom category value.
* `page`: `contains_case_insensitive` with one non-empty value. This searches
the normalized page URL.
`include_cited_websites: true` applies only to response sentiment grouped by
`theme` and/or `claim`.
Citation sentiment describes the cited page. A model filter changes which
models' citations contribute to page eligibility and citation share; it does
not turn page sentiment into a model-specific sentiment score.
New to the v2 reports? See [Filtering & concepts](/rest-api/reports/reports-v2-overview) for the shared request shape, filter tree, grouping, and pagination.
`POST /v2/reports/sentiment/stream` supports both response and citation
sentiment and returns [Server-Sent Events](https://developer.mozilla.org/docs/Web/API/Server-sent_events):
one `summary` event (the `info` block), then one `result` event per row.
`limit`/`cursor` are ignored; it returns everything by default. Pass
`max_results` to cap. With `source: "citation"`, each `result` is the same
page-level shape returned in `data` by the paginated endpoint.
```text Response (text/event-stream) theme={null}
event: summary
data: { ...the info block... }
event: result ← one per row, same shape as data[] above
data: {"theme": {"id": "a14e0c2d", "name": "Analytics"}, "rank": 1, "positive_sentiment": 95.4, "negative_sentiment": 4.6}
```
```bash cURL theme={null}
curl -X POST https://api.tryprofound.com/v2/reports/sentiment \
-H "X-API-Key: " \
-H "Content-Type: application/json" \
-d '{
"category_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
"asset": "Profound",
"start_date": "2026-06-09",
"end_date": "2026-06-15"
}'
```
```json 200 theme={null}
{
"info": {
"total_results": 1,
"count": 1,
"next_cursor": null,
"asset": "Profound",
"models": ["ChatGPT", "Google Gemini", "Perplexity", "Claude", "..."],
"metrics": ["positive_sentiment", "negative_sentiment"],
"start_date": "2026-06-09",
"end_date": "2026-06-15",
"filter": null
},
"data": [
{
"positive_sentiment": 79.1,
"negative_sentiment": 20.9
}
]
}
```
## Citation-page example
This request returns owned pages containing `tryprofound.com`, ordered by their
current citation share. Combine citation-layer leaves with other filters under a
top-level `and`.
```bash cURL theme={null}
curl -X POST https://api.tryprofound.com/v2/reports/sentiment \
-H "X-API-Key: " \
-H "Content-Type: application/json" \
-d '{
"category_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
"asset": "Profound",
"start_date": "2026-06-09",
"end_date": "2026-06-15",
"source": "citation",
"metrics": ["positive_sentiment", "negative_sentiment", "citation_share"],
"sort": {"field": "citation_share", "dir": "desc"},
"filter": {
"and": [
{"field": "citation_category", "op": "is", "value": "owned"},
{"field": "page", "op": "contains_case_insensitive", "value": "tryprofound.com"}
]
},
"limit": 10
}'
```
```json 200 theme={null}
{
"info": {
"total_results": 1,
"count": 1,
"next_cursor": null,
"asset": "Profound",
"models": ["ChatGPT", "Google Gemini", "Perplexity", "..."],
"metrics": ["positive_sentiment", "negative_sentiment", "citation_share"],
"start_date": "2026-06-09",
"end_date": "2026-06-15",
"filter": {
"and": [
{"field": "citation_category", "op": "is", "value": "owned"},
{"field": "page", "op": "contains_case_insensitive", "value": "tryprofound.com"}
]
}
},
"data": [
{
"page": "tryprofound.com/",
"rank": 1,
"positive_sentiment": 100.0,
"negative_sentiment": 0.0,
"citation_share": 1.42
}
]
}
```
## OpenAPI
````yaml POST /v2/reports/sentiment
openapi: 3.1.0
info:
title: External API
version: 0.60.2
x-scalar-sdk-installation:
- lang: Python
description: |-
```sh
pip install profound
```
- lang: TypeScript
description: |-
```sh
npm install @profoundai/client
```
- lang: Rust
description: |-
```sh
cargo add profound
```
servers:
- url: https://api.tryprofound.com
description: Production Server
security:
- APIKeyHeader:
- X-API-Key
- BearerAuth: []
paths:
/v2/reports/sentiment:
post:
tags:
- Reports
- Reports
summary: Query Sentiment V2
operationId: query_sentiment_v2_v2_reports_sentiment_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SentimentV2Query'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SentimentV2Response'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- BearerAuth: []
x-codeSamples:
- label: Python
lang: Python
source: |-
import os
from profound import Profound
client = Profound(
api_key=os.environ.get("PROFOUND_API_KEY"),
)
report = client.reports.query_sentiment(
category_id="7c9e6679-7425-40de-944b-e07fc1f90ae7",
asset="",
start_date="",
end_date="",
source="response",
interval="day",
include_cited_websites=False,
)
print(report)
- label: TypeScript
lang: TypeScript
source: |-
import Profound from '@profoundai/client';
const client = new Profound({
apiKey: process.env['PROFOUND_API_KEY'], // defaults to the PROFOUND_API_KEY env var
environment: 'production',
});
const report = await client.reports.querySentiment({
category_id: '7c9e6679-7425-40de-944b-e07fc1f90ae7',
asset: '',
start_date: '',
end_date: '',
source: 'response',
interval: 'day',
include_cited_websites: false,
});
console.log(report);
- label: rust
lang: rust
source: |-
use profound::*;
#[tokio::main]
async fn main() -> Result<(), Box> {
let client = ProfoundClient::builder()
.api_key(std::env::var("PROFOUND_API_KEY")?)
.build()?;
let response = client
.reports()
.query_sentiment(SentimentV2Query {
category_id: "7c9e6679-7425-40de-944b-e07fc1f90ae7".to_string(),
asset: "".to_string(),
start_date: "".to_string(),
end_date: "".to_string(),
comparison_start_date: None,
comparison_end_date: None,
source: None,
group_by: None,
metrics: None,
interval: None,
filter: None,
sort: None,
include_cited_websites: None,
limit: None,
max_results: None,
cursor: None,
})
.send()
.await?;
println!("{:?}", response);
Ok(())
}
components:
schemas:
SentimentV2Query:
properties:
category_id:
type: string
format: uuid
title: Category Id
asset:
type: string
title: Asset
description: The brand name to analyze (sentiment is extracted on name, not id).
start_date:
type: string
title: Start Date
description: YYYY-MM-DD, ET, inclusive
end_date:
type: string
title: End Date
description: YYYY-MM-DD, ET, inclusive
comparison_start_date:
anyOf:
- type: string
- type: 'null'
title: Comparison Start Date
description: YYYY-MM-DD, ET, inclusive (with end).
comparison_end_date:
anyOf:
- type: string
- type: 'null'
title: Comparison End Date
description: YYYY-MM-DD, ET, inclusive (with start).
source:
type: string
enum:
- response
- citation
title: Source
default: response
group_by:
items:
type: string
enum:
- date
- model
- topic
- region
- prompt
- persona
- tag
- theme
- claim
- run
- competitor
type: array
title: Group By
metrics:
anyOf:
- items:
type: string
enum:
- positive_sentiment
- negative_sentiment
- occurrence
- citation_share
type: array
- type: 'null'
title: Metrics
interval:
type: string
enum:
- day
- week
- month
title: Interval
default: day
filter:
anyOf:
- $ref: '#/components/schemas/FilterNode'
- type: 'null'
sort:
$ref: >-
#/components/schemas/app__routes__v2__answer_engine_insights__reports__sentiment__SortSpec
include_cited_websites:
type: boolean
title: Include Cited Websites
description: >-
Return cited websites per row (only when grouping by
`theme`/`claim`).
default: false
limit:
anyOf:
- type: integer
maximum: 50
exclusiveMinimum: 0
- type: 'null'
title: Limit
description: Page size; default 10, max 50.
max_results:
anyOf:
- type: integer
exclusiveMinimum: 0
- type: 'null'
title: Max Results
description: >-
Stream endpoint only: cap the number of streamed rows (default:
all).
cursor:
anyOf:
- type: string
- type: 'null'
title: Cursor
additionalProperties: false
type: object
required:
- category_id
- asset
- start_date
- end_date
title: SentimentV2Query
SentimentV2Response:
properties:
info:
$ref: '#/components/schemas/SentimentV2Info'
data:
items:
$ref: '#/components/schemas/SentimentRow'
type: array
title: Data
type: object
required:
- info
- data
title: SentimentV2Response
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
FilterNode:
properties:
and:
anyOf:
- items:
$ref: '#/components/schemas/FilterNode'
type: array
- type: 'null'
title: And
or:
anyOf:
- items:
$ref: '#/components/schemas/FilterNode'
type: array
- type: 'null'
title: Or
not:
anyOf:
- $ref: '#/components/schemas/FilterNode'
- type: 'null'
field:
anyOf:
- type: string
- type: 'null'
title: Field
op:
anyOf:
- type: string
- type: 'null'
title: Op
value:
title: Value
additionalProperties: false
type: object
title: FilterNode
description: A leaf (`field`/`op`/`value`) or an `and`/`or`/`not` group.
app__routes__v2__answer_engine_insights__reports__sentiment__SortSpec:
properties:
field:
type: string
enum:
- occurrence
- positive_sentiment
- negative_sentiment
- citation_share
title: Field
default: positive_sentiment
dir:
type: string
enum:
- asc
- desc
title: Dir
default: desc
type: object
title: SortSpec
SentimentV2Info:
properties:
total_results:
anyOf:
- type: integer
- type: 'null'
title: Total Results
description: >-
Total rows matching the query before pagination (null when not
computed).
count:
type: integer
title: Count
description: Number of rows returned in `data` for this page.
next_cursor:
anyOf:
- type: string
- type: 'null'
title: Next Cursor
description: Opaque cursor for the next page; null on the last page.
models:
items:
type: string
type: array
title: Models
description: Display names of the models the report covers.
start_date:
type: string
title: Start Date
description: Echoed request start date (YYYY-MM-DD, ET).
end_date:
type: string
title: End Date
description: Echoed request end date (YYYY-MM-DD, ET).
filter:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Filter
description: Echoed normalized filter tree, or null when no filter was sent.
asset:
type: string
title: Asset
description: The analyzed brand name.
metrics:
items:
type: string
type: array
title: Metrics
description: Sentiment metrics returned per row.
comparison_start_date:
anyOf:
- type: string
- type: 'null'
title: Comparison Start Date
description: Comparison-window start (when requested).
comparison_end_date:
anyOf:
- type: string
- type: 'null'
title: Comparison End Date
description: Comparison-window end (when requested).
additionalProperties: true
type: object
required:
- count
- models
- start_date
- end_date
- asset
- metrics
title: SentimentV2Info
SentimentRow:
properties:
date:
anyOf:
- type: string
- type: 'null'
title: Date
model:
anyOf:
- $ref: '#/components/schemas/DimensionRef'
- type: 'null'
topic:
anyOf:
- $ref: '#/components/schemas/DimensionRef'
- type: 'null'
region:
anyOf:
- $ref: '#/components/schemas/DimensionRef'
- type: 'null'
prompt:
anyOf:
- $ref: '#/components/schemas/DimensionRef'
- type: 'null'
persona:
anyOf:
- $ref: '#/components/schemas/DimensionRef'
- type: 'null'
tag:
anyOf:
- $ref: '#/components/schemas/DimensionRef'
- type: 'null'
theme:
anyOf:
- $ref: '#/components/schemas/DimensionRef'
- type: 'null'
claim:
anyOf:
- $ref: '#/components/schemas/DimensionRef'
- type: 'null'
run:
anyOf:
- $ref: '#/components/schemas/DimensionRef'
- type: 'null'
competitor:
anyOf:
- $ref: '#/components/schemas/DimensionRef'
- type: 'null'
page:
anyOf:
- type: string
- type: 'null'
title: Page
positive_sentiment:
anyOf:
- type: number
- type: 'null'
title: Positive Sentiment
negative_sentiment:
anyOf:
- type: number
- type: 'null'
title: Negative Sentiment
occurrence:
anyOf:
- type: number
- type: 'null'
title: Occurrence
citation_share:
anyOf:
- type: number
- type: 'null'
title: Citation Share
previous:
anyOf:
- $ref: '#/components/schemas/SentimentMetrics'
- type: 'null'
description: Comparison-window metrics (when requested).
prev_date:
anyOf:
- type: string
- type: 'null'
title: Prev Date
cited_websites:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Cited Websites
rank:
anyOf:
- type: integer
- type: 'null'
title: Rank
additionalProperties: true
type: object
title: SentimentRow
description: >-
One group-combination row. Group dims and metrics present depend on
`group_by`/`metrics`.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
DimensionRef:
properties:
id:
anyOf:
- type: string
- type: 'null'
title: Id
name:
anyOf:
- type: string
- type: 'null'
title: Name
type: object
title: DimensionRef
description: An ``{id, name}`` reference for a grouped dimension value.
SentimentMetrics:
properties:
positive_sentiment:
anyOf:
- type: number
- type: 'null'
title: Positive Sentiment
negative_sentiment:
anyOf:
- type: number
- type: 'null'
title: Negative Sentiment
occurrence:
anyOf:
- type: number
- type: 'null'
title: Occurrence
citation_share:
anyOf:
- type: number
- type: 'null'
title: Citation Share
additionalProperties: true
type: object
title: SentimentMetrics
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: X-API-Key
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````