> ## Documentation Index
> Fetch the complete documentation index at: https://docs.particle.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Speaker statement characteristics

> How each returned line is said: its sentiment, certainty, specificity and temporal orientation, as labels on search and mention results, and as a filter.

Lines returned by [episode search](https://docs.particle.pro/podcasts/episode-search.md) and [mentions](https://docs.particle.pro/podcasts/mentions.md) carry `speaker_statement_characteristics`: four labels that describe *how* a line is said, not what it is about. Use them to tell a confident prediction from a hedged aside, or a pointed criticism from a passing remark, without reading every line.

```json theme={"dark"}
{
  "number": 412,
  "speaker": "Jane Doe",
  "role": "GUEST",
  "text": "Within five years, most new drug programs will start from a model, not a wet lab.",
  "speaker_statement_characteristics": {
    "sentiment": "positive",
    "certainty": "confident",
    "specificity": "specific",
    "temporal_orientation": "future"
  }
}
```

## The four axes

| Axis | Labels | What it reads |
| - | - | - |
| `sentiment` | `negative` · `neutral` · `positive` | The statement's tone. |
| `certainty` | `hedged` · `neutral` · `confident` | How sure the speaker sounds: "maybe", "I think", "it could" against a flat assertion. |
| `specificity` | `vague` · `neutral` · `specific` | Whether the line commits to something concrete (names, numbers, dates, mechanisms) or stays general. |
| `temporal_orientation` | `past` · `present` · `future` | Whether the line looks back, describes how things are, or looks ahead (predictions, plans, expectations). |

Combinations read naturally: `specific` + `future` is a concrete prediction, `confident` + `positive` + `future` is a bullish call, and `negative` + `specific` is a pointed criticism.

## What a label means

* **A pole label means the line clearly reads that way.** `positive`, `hedged`, `specific`, `future` and the other poles are assigned only when the reading is clear.
* **The middle label means "not clearly either pole".** A borderline line takes `neutral` (or `present` for `temporal_orientation`), so the middle label is not a measurement of neutrality. Most lines sit in the middle on at least one axis.
* **Labels describe one statement, not the speaker.** A guest who is bullish on a company can still make a hedged, backward-looking remark about it.
* **Labels are read from the words.** Tone of voice is not part of the reading, so sarcasm and irony can be misread.
* **Labels keep their meaning over time.** When the model that reads lines improves, each new version is held to the same standard before it labels anything.

## Which lines carry them

* Lines in topic-discussion and interview segments. Lines in intros, outros, ad reads and other structural segments carry none, and neither do short lines such as "Yeah." or "I don't know."
* Every line of a returned window: the `is_match` and `is_mention` lines and the context lines around them.
* The object is absent, not `null`, on a line without labels.

Labels ride on the lines a query returns. Whole-transcript endpoints, such as [transcripts](https://docs.particle.pro/podcasts/transcripts.md) and [segments](https://docs.particle.pro/podcasts/segments-and-clips.md), do not carry them.

## Filtering by characteristics

Both endpoints take the same labels as a filter, `speaker_statement_characteristics`, which keeps only lines said a certain way. Each axis is a key, and its value is one or more of that axis's labels, comma-separated:

```bash theme={"dark"}
curl -G "https://api.particle.pro/v1/podcasts/episodes/search" \
  -H "X-API-Key: $PARTICLE_API_KEY" \
  --data-urlencode "semantic_search=AI drug discovery" \
  --data-urlencode "speaker_statement_characteristics[certainty]=confident" \
  --data-urlencode "speaker_statement_characteristics[temporal_orientation]=future"
```

Mentions take the same filter, with the subject naming what is spoken of. Criticism of Nvidia:

```bash theme={"dark"}
curl -G "https://api.particle.pro/v1/podcasts/mentions" \
  -H "X-API-Key: $PARTICLE_API_KEY" \
  --data-urlencode "company_id=nvidia" \
  --data-urlencode "speaker_statement_characteristics[sentiment]=negative"
```

* **Labels on one axis match any of them.** `speaker_statement_characteristics[sentiment]=positive,negative` keeps lines that lean clearly either way. List every label in one value: repeating the key (`[sentiment]=positive&[sentiment]=negative`) keeps only one of them.
* **Use the bracketed form.** A flat `sentiment=positive` is not this filter: it is ignored, and the results come back unfiltered.
* **Axes combine with AND.** Add only the axes you mean. An axis you leave out does not constrain anything.
* **Every marked line meets the filter.** On a filtered search, every `is_match` line carries labels the filter accepts, and a segment is returned only when one of its lines does. On filtered mentions, every `is_mention` line does, and an episode is returned only when one of its mentions does. Context lines around them are returned as usual, with their own labels.
* **An unknown axis or label is a `422`** that names it. For an unknown label, the error also lists the axis's valid labels.

Put the topic in `semantic_search` and how it is said in the filter. "Optimistic predictions about AI drug discovery" is `semantic_search=AI drug discovery` with `positive` and `future`, not a longer search phrase. Mentions take no topic text: the subject (`entity_id` or `company_id`) is what is spoken of, and the filter is how.

### Recipes

| You want | Filter |
| - | - |
| Predictions | `specificity=specific`, `temporal_orientation=future` |
| A high-conviction outlook | `certainty=confident`, `sentiment=positive`, `temporal_orientation=future` |
| Criticism of a company | Mentions with `company_id`, and `sentiment=negative` |
| What cardiologists predict | `guest_occupation=cardiologists`, `temporal_orientation=future` |
| Hedged takes | `certainty=hedged` |
| Concrete claims | `specificity=specific` |
| Looking back | `temporal_orientation=past` |

### Without a topic

Leave `semantic_search` and `keyword_search` out, and episode search returns the **strongest lines** said the way the filter asks: the lines that carry its labels most clearly, strongest first, **at most 50**. Scope it to one episode with `episode_id`, or to people with `speaker` or the `guest_` filters:

```bash theme={"dark"}
# The boldest predictions in one episode
curl -G "https://api.particle.pro/v1/podcasts/episodes/search" \
  -H "X-API-Key: $PARTICLE_API_KEY" \
  --data-urlencode "episode_id=<episode slug>" \
  --data-urlencode "speaker_statement_characteristics[certainty]=confident" \
  --data-urlencode "speaker_statement_characteristics[temporal_orientation]=future"
```

* Each match's `match.source` is `characteristics`, and it carries no `relevance_score`.
* A line is strongest when its labels are least borderline. A flat assertion about a far-off future outranks a line just past the confident cut.
* Without a topic, `entity_id`, `company_id` and `entity_type` return `422`. For lines naming an entity said a certain way, use [mentions](https://docs.particle.pro/podcasts/mentions.md) with the same filter.

### What the filter serves

* **Episode search** takes the topic as `semantic_search`, or no topic at all (see [Without a topic](#without-a-topic)). A `keyword_search` alone returns `422`, because the filter reads lines found by meaning. Unquoted `keyword_search` words can join `semantic_search` to require those words in the segment (the default `keyword_match=required`). A quoted phrase returns `422`, because a matched line cannot be required to say the phrase as well, and so does `keyword_match=ranked`, because filtered segments rank by their lines' meaning and a ranking hint would change nothing. `entity_id`, `company_id`, `entity_type`, `role`, `podcast_id`, `episode_id`, `language`, `since`, `until`, `sort`, `speaker` and the `guest_` filters all combine with the filter.
* **Mentions** need a subject with a knowledge graph entity. A subject matched by name returns `422`. A filtered page checks a bounded number of candidate episodes, so a rare combination can return a short page with a `cursor`: follow it to keep reading.
* **Whose lines.** With `speaker` or the `guest_` filters, only the lines the people they select say count, on both endpoints: confident predictions by cardiologists are `guest_occupation=cardiologists` with `certainty=confident` and `temporal_orientation=future`, and every `is_match` or `is_mention` line is one of theirs. On search:
  * When more than 10,000 of their lines carry the labels, the newest 10,000 are searched. Narrow with `since`, `until`, `podcast_id` or another label to reach older ones.
  * The `guest_` filters must name `guest_occupation`, `guest_field` or `guest_capacity`, which the other `guest_` filters narrow, and may select at most 5,000 guests with at most 50,000 appearances between them. A broader filter returns `422`; narrow it with `guest_practicing`, `guest_seniority`, `guest_standing` or a narrower `guest_occupation`.
  * `speaker` must be a person with a person record; one known only as an entity returns `422`.

## How a subject is spoken of

[Share of voice](https://docs.particle.pro/people/expertise.md#how-they-said-it) counts an entity's or a company's
mentions by their labels instead of returning them:

| Question | Parameters on `/v1/podcasts/mentions/share-of-voice` |
| - | - |
| How negatively or positively is it spoken of? | `by=sentiment` |
| How does each profession speak of it? | `breakdown=sentiment` (groups stay occupations) |
| Who makes predictions about it? | `speaker_statement_characteristics[temporal_orientation]=future` |
| How sure are the predictions? | `by=temporal_orientation&breakdown=certainty` |

Shares there are of `scored_mentions`, the lines that carry labels, and a group on fewer
than 20 of them is `low_sample`. `examples=3` adds the three lines that most clearly
carry each label, with who said them and a link to the moment, so a share comes with
what was actually said.

## How a person speaks over time

`GET /v1/people/{id}/statement-characteristics` counts one person's labelled lines over a window, the last year by default. On each axis it gives every label's share of their scored lines, for the whole window and per `week` or `month` bucket:

```bash theme={"dark"}
curl -H "X-API-Key: $PARTICLE_API_KEY" \
  "https://api.particle.pro/v1/people/sam-altman/statement-characteristics?interval=month&examples=1"
```

Each bucket names its strongest lines for every outer label (negative and positive, hedged and confident, vague and specific, past and future). These are the lines reading furthest past the label's cut, each with its episode and a link that plays it. `low_sample` marks a share resting on fewer than 20 scored lines. The MCP twin is [`particle_person_get_statement_characteristics`](https://docs.particle.pro/mcp/tools/people/person-get-statement-characteristics).

## In MCP

[`particle_podcast_search_transcripts`](https://docs.particle.pro/mcp/tools/podcasts/podcast-search-transcripts) and [`particle_podcast_find_mentions`](https://docs.particle.pro/mcp/tools/podcasts/podcast-find-mentions) end each line with its pole labels, for example `_[confident · positive · future]_`. Middle labels are left out of that short form; `_[neutral]_` marks a line that leans clearly on no axis, and a line without brackets carries no labels. With `output_format=json`, each line has the full `speaker_statement_characteristics` object.

Both tools take the filter as one object argument, `speaker_statement_characteristics`, whose axes are arrays of labels: `{"certainty": ["confident"], "temporal_orientation": ["future"]}`. [`particle_podcast_get_share_of_voice`](https://docs.particle.pro/mcp/tools/podcasts/podcast-get-share-of-voice) takes the same argument, and `by` and `breakdown` with the axes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.