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

# Decisions

> Decision models that answer questions about text and images with probabilities.

## Overview

A decision model reads text and images the way a multimodal language model does, but instead of writing text it returns typed answers with probabilities. It does not write replies, generate code, or explain its reasoning; your code does the reasoning with the numbers it returns.

Use it where you would otherwise ask a chat model for a label and parse the reply: classifying, routing, grading against a rubric, extracting spans, or any decision you want to threshold. You get numbers you can compare against a cutoff, no output parsing, and as many questions as you need about the same content in one request.

You send the content as `state`, attach one or more named questions, and get one answer per question:

| Question type | You ask | You get back |
| - | - | - |
| **`noul`** | A yes/no question, or a statement to check | The probability of yes, from 0 to 1 |
| **`choice`** | Pick one of the options you define | A probability for every option, plus the most likely one |
| **`score`** | Rate the content on an ordered rubric | A probability for every level, plus the expected score |
| **`locate`** | Find text in the content that matches a description | The matching spans of `state`, with offsets and scores |

## Models

| Model | Alias | Parameters | Price (\$/1M input tokens) |
| - | - | :-: | :-: |
| `pplx-decider-v1.3` | `pplx-decider-latest` | 27B | \$0.02 |
| `pplx-decider-flash-v1.3` | `pplx-decider-flash-latest` | 4B | \$0.01 |

* **`pplx-decider-latest`:** Recommended default. Start here for nuanced judgments, such as grading against a detailed rubric or checking a claim against long source text, or where a wrong answer is costly.
* **`pplx-decider-flash-latest`:** Choose for high-volume decisions with clear criteria, such as routing, labeling, filtering, or simple extraction, where half the input price matters.

Both models accept text and images, have a 256K-token context window, answer all four question types, and take the same request. Output tokens are free and there is no per-request fee; input tokens are `usage.input_tokens` in each response.

An alias follows the newest version of its model and can move to a newer decision model; the [changelog](https://docs.perplexity.ai/docs/resources/changelog.md) announces the change. To keep thresholds stable, name the versioned model; see [recalibrating thresholds](#previous-versions) when you switch. `perplexity/pplx-decider-latest` and `perplexity/pplx-decider-flash-latest` are also accepted. The response `model` field echoes the name you sent.

## Basic Usage

Every question in a request refers to the same `state`. You name each question, and the response uses the same names.

```python Python theme={null}
from perplexity import Perplexity

client = Perplexity(timeout=30.0)

response = client.decisions.create(
    model="pplx-decider-latest",
    state={
        "title": "Battery died after two weeks",
        "review": "The headphones sound great, but the battery stopped charging after two weeks.",
    },
    questions={
        "defect": {"type": "noul", "instructions": "Does the review report a product defect?"},
        "sentiment": {"type": "choice", "instructions": "What is the overall sentiment of the review?",
                      "criteria": {"positive": "Mostly satisfied", "mixed": "Praise and complaints in one review", "negative": "Mostly dissatisfied"}},
        "severity": {"type": "score", "instructions": "How severe is the reported problem?",
                     "criteria": ["Cosmetic", "Inconvenient", "Product unusable"]},
    },
)

print(response.to_json())
```

```typescript Typescript theme={null}
import Perplexity from "@perplexity-ai/perplexity_ai";

const client = new Perplexity({ timeout: 30_000 });

const response = await client.decisions.create({
  model: "pplx-decider-latest",
  state: {
    title: "Battery died after two weeks",
    review: "The headphones sound great, but the battery stopped charging after two weeks.",
  },
  questions: {
    defect: { type: "noul", instructions: "Does the review report a product defect?" },
    sentiment: { type: "choice", instructions: "What is the overall sentiment of the review?",
      criteria: { positive: "Mostly satisfied", mixed: "Praise and complaints in one review", negative: "Mostly dissatisfied" } },
    severity: { type: "score", instructions: "How severe is the reported problem?",
      criteria: ["Cosmetic", "Inconvenient", "Product unusable"] },
  },
});

console.log(JSON.stringify(response, null, 2));
```

```bash cURL theme={null}
curl -X POST 'https://api.perplexity.ai/v1/decisions' \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "pplx-decider-latest",
    "state": {
      "title": "Battery died after two weeks",
      "review": "The headphones sound great, but the battery stopped charging after two weeks."
    },
    "questions": {
      "defect": {"type": "noul", "instructions": "Does the review report a product defect?"},
      "sentiment": {"type": "choice", "instructions": "What is the overall sentiment of the review?",
        "criteria": {"positive": "Mostly satisfied", "mixed": "Praise and complaints in one review", "negative": "Mostly dissatisfied"}},
      "severity": {"type": "score", "instructions": "How severe is the reported problem?",
        "criteria": ["Cosmetic", "Inconvenient", "Product unusable"]}
    }
  }' | jq
```

> [accordion] Response
>
> ```json theme={null}
> {
>   "model": "pplx-decider-latest",
>   "answers": {
>     "defect": {"type": "noul", "noul": 0.9424522889347015},
>     "sentiment": {
>       "type": "choice", "choice": "mixed", "confidence": 0.9255246944002182,
>       "probabilities": {"positive": 0.020649883775315993, "mixed": 0.9503497962668123, "negative": 0.02900031995787183}
>     },
>     "severity": {
>       "type": "score", "score": 1.7838686319784252, "confidence": 0.7838686319784252,
>       "legend": {"0": "Cosmetic", "1": "Inconvenient", "2": "Product unusable"},
>       "probabilities": {"0": 0.008423954913615923, "1": 0.199283458194343, "2": 0.7922925868920411}
>     }
>   },
>   "usage": {"input_tokens": 367, "output_tokens": 3}
> }
> ```

Exact probabilities depend on the model that serves the request. Identical requests usually return identical numbers, but they can differ in the second decimal place, so set thresholds with some margin.

### `noul`

Give `instructions`, `criteria`, or both; `criteria` defines what counts as yes and what counts as no. A `noul` with neither returns `400`.

```json theme={null}
{"type": "noul", "instructions": "Does the review report a product defect?",
 "criteria": {"true": "Something is broken or not working.", "false": "Normal wear or personal preference."}}
```

The answer is `noul`, the probability of yes, from 0 to 1, for example `{"type": "noul", "noul": 0.94}`. Values near 0.5 mean the model is unsure.

### `choice`

`criteria` maps each option name to a description of when it applies, or to `null` to let the name speak for itself.

```json theme={null}
{"type": "choice", "instructions": "Which team should handle this ticket?",
 "criteria": {"billing": "Charges, refunds, and invoices", "shipping": "Delivery status and lost packages", "other": null}}
```

The answer has `choice` (the most likely option), `probabilities` (one value per option, summing to about 1), and `confidence`, as in `sentiment` above.

### `score`

`criteria` is an ordered array of level descriptions; the index is the level's score, starting at 0. Use at least two levels: a single level always answers 0 with probability 1.

```json theme={null}
{"type": "score", "instructions": "How severe is the reported problem?", "criteria": ["Cosmetic", "Inconvenient", "Product unusable"]}
```

The answer has `score` (the probability-weighted average of the level indices, so it can fall between levels), `legend` (each index mapped back to your rubric), `probabilities` (keyed like `legend`), and `confidence`. In `severity` above, 1.78 sits between `Inconvenient` and `Product unusable`, closer to 2.

`confidence` on `choice` and `score` answers runs from 0 to 1 and is computed from `probabilities`; it is not the top probability:

* **`choice`:** `(p_top - 1/n) / (1 - 1/n)` for `n` options. For `sentiment`, (0.95 - 1/3) / (2/3) = 0.93.
* **`score`:** `1 - spread / baseline`, floored at 0, where `spread` is the sum of `p_i × |i - top|` and `baseline` is the unweighted mean of `|i - top|` over all levels. For `severity`, (0.0084 × 2 + 0.1993 × 1) / 1 = 0.216, so `confidence` is 0.78.

A single option or level has a `confidence` of 1.

### `locate`

Describe what to find in `instructions`, such as `"email address"` or `"Extract the city where the job is located."` Use it for named entities, personal information, or extractive question answering. `criteria` is ignored.

```json theme={null}
{"type": "locate", "instructions": "email address"}
```

For the `state` `"The AeroPress arrived with a cracked filter cap. I emailed help@brewco.example on Monday and nobody replied."`, `pplx-decider-v1.3` returned:

```json theme={null}
{"type": "locate", "spans": [{"start": 59, "end": 78, "text": "help@brewco.example", "score": 0.999974250793457}]}
```

Each span has `text` (a verbatim substring of `state`), `start` and `end` (Unicode character offsets, `end` exclusive), and `score`. `spans` is `[]` when nothing matches. `state` must be a string without images; otherwise it returns `400`. With [web grounding](#web-grounding), a span found in the evidence adds `search_result`, the index of that result, with offsets in its `snippet`. Locate was evaluated on inputs of up to 32K tokens.

## Advanced Usage

### Ask about images

To classify a screenshot, check a photo, or answer any question about an image, put the image in `state`. Write each image as an OpenAI-style part anywhere in `state`, as an array item or an object value at any depth. The model sees images exactly where their parts appear:

```json theme={null}
"state": ["Which color is the square?", {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}}]
```

PNG, JPEG, and WebP data URLs are accepted; `http` or `https` image URLs return `400`. An image over the [size limit](#request-limits) (1440 × 1440 and 2048 × 1024 fit; 1600 × 1310 does not) returns `504` after about a minute, so resize before you send. An image costs about 1,000 input tokens per megapixel.

### Grouping questions

All questions in a request are answered in one pass and the `state` is billed once. Each question sees the `state` and its own text, not the other questions. Questions can still affect one another a little through the shared `state`, so keep the grouping fixed when you compare runs or tune thresholds.

If the `state` plus all questions goes over the input limit, the API answers the questions in consecutive groups, and each group counts the `state` again in `usage.input_tokens`. A split request takes longer. If the `state` plus a single question is over the limit, the request returns `400`. [Previous versions](#previous-versions) group questions differently.

### Web grounding

A decision model only knows what is in `state` and what it learned in training. Turn on web grounding when the answer depends on facts that are not in your `state`: checking whether a claim is true, answering about recent events, or verifying names, dates, and numbers in your content. Set `mode` to `"web_grounding"`, and before the model answers, the API runs one Perplexity [Fast Search](https://docs.perplexity.ai/docs/search/fast-search.md) per question and adds the top results to `state` as evidence.

This request checks one claim. The SDKs do not have a typed `mode` field yet, so Python passes it in `extra_body` and TypeScript spreads it into the request:

```python Python theme={null}
from perplexity import Perplexity

client = Perplexity(timeout=30.0)

response = client.decisions.create(
    model="pplx-decider-latest",
    state="Claim: The James Webb Space Telescope launched in December 2021.",
    questions={"supported": {"type": "noul", "instructions": "Is the claim true?"}},
    extra_body={"mode": "web_grounding"},  # the library has no `mode` parameter yet
)

print(response.to_json())
```

```typescript Typescript theme={null}
import Perplexity from "@perplexity-ai/perplexity_ai";

const client = new Perplexity({ timeout: 30_000 });

const response = await client.decisions.create({
  model: "pplx-decider-latest",
  state: "Claim: The James Webb Space Telescope launched in December 2021.",
  questions: { supported: { type: "noul", instructions: "Is the claim true?" } },
  ...{ mode: "web_grounding" },  // the SDK types have no `mode` field yet
});

console.log(JSON.stringify(response, null, 2));
```

```bash cURL theme={null}
curl -X POST 'https://api.perplexity.ai/v1/decisions' \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "pplx-decider-latest",
    "mode": "web_grounding",
    "state": "Claim: The James Webb Space Telescope launched in December 2021.",
    "questions": {"supported": {"type": "noul", "instructions": "Is the claim true?"}}
  }' | jq
```

The response adds `search_results`, the evidence the model saw, and `usage.tool_calls_details`, the searches and fetches you are billed for. See the [API reference](https://docs.perplexity.ai/api-reference/decisions-post.md) for every field.

> [accordion] Response (one of five search results, snippet shortened)
>
> ```json theme={null}
> {
>   "model": "pplx-decider-latest",
>   "answers": {"supported": {"type": "noul", "noul": 0.9983307784830786}},
>   "usage": {"input_tokens": 1663, "output_tokens": 1, "tool_calls_details": {"search_web": {"invocation": 1}}},
>   "search_results": [
>     {
>       "title": "NASA - NSSDCA - Spacecraft - Details",
>       "url": "https://nssdc.gsfc.nasa.gov/nmc/spacecraft/display.action?id=2021-130A",
>       "snippet": "... JWST launched on 25 December 2021 ...",
>       "last_updated": "2026-11-04"
>     }
>   ]
> }
> ```

If no search returns a result in time, the model answers from `state` alone and `search_results` is `[]`.

> [accordion] How queries and evidence are built
>
> * **Queries:** each question becomes one search query: the question text (its `instructions` and criteria) followed by the start of your `state` text, 256 bytes in all. With `state` text, the question part gets at most 128 bytes. Images are not searched, questions with the same query share one search, and empty queries are skipped.
> * **Evidence:** results are deduplicated by URL and added to `state`. A string `state` gets them after an `Evidence:` line, an array `state` gets them as extra items, and an object `state` becomes an array of the object followed by the results.
> * **Time:** searches run up to 10 at a time, with 1 second each. A search that runs out of time adds no results.
> * **Failures:** if some searches fail, the API uses the others. If none returns a result, or no question has text to search, the model answers from `state`, including any fetched page text.
> * **Privacy:** queries contain your question text and the start of your `state` text, and go to Fast Search.

#### Ask about a web page

To ask about a specific page, send its URL as the whole `state`:

```json theme={null}
"state": "https://en.wikipedia.org/wiki/James_Webb_Space_Telescope"
```

The API fetches the page, puts its text in `state`, and then searches as usual, so the request is billed for one fetch plus the searches. The response adds `fetched_results` with the page text the model read. If the fetch fails, `fetched_results` is absent and the model sees only the URL. Only a URL on its own is fetched; a URL inside other text is treated as text.

#### Web grounding cost

Each search costs \$0.001 and each page fetch \$0.0005, on top of input tokens ([Pricing](https://docs.perplexity.ai/docs/getting-started/pricing.md#web-grounding)). Evidence and fetched text count as input tokens, so they also count toward the [input limit](#request-limits). For example, the claim check above used 1 search and 1,663 input tokens on `pplx-decider-latest`: \$0.001 + \$0.00003, about \$1.03 per 1,000 grounded questions.

## Inputs

| `state` | Use |
| - | - |
| String | Plain text. Required for `locate` questions |
| Object | Structured content, such as fields of a record. The model reads it as JSON |
| Array | Several items in order, such as text next to images |
| Image part | A single image as the whole content; see [Ask about images](#ask-about-images) |
| Single URL, with `mode: "web_grounding"` | The page text replaces the URL; see [Ask about a web page](#ask-about-a-web-page) |

`null` returns `400`. `score` levels must not be `null`; `choice` descriptions can be.

## Parameters

Use `POST https://api.perplexity.ai/v1/decisions` with `Authorization: Bearer <PERPLEXITY_API_KEY>`. An unknown top-level field returns `400`.

| Parameter | Type | Required | Default | Description |
| - | - | :-: | :-: | - |
| `model` | string | Yes | - | `pplx-decider-latest`, `pplx-decider-flash-latest`, or a versioned name. See [Models](#models). |
| `state` | string \| object \| array | Yes | - | The content to evaluate. See [Inputs](#inputs). |
| `questions` | object | Yes | - | Questions keyed by a non-empty name. Each has `type` (`noul`, `choice`, `score`, or `locate`), `instructions`, and, depending on the type, `criteria`. |
| `mode` | string | No | - | `web_grounding` searches the web before the model answers. Any other value returns `400`. |
| `max_staleness` | integer | No | - | Accepted but currently ignored. It does not check the age of a fetched page or trigger a crawl. |

## Request Limits

| Limit | Value |
| - | - |
| Questions per request | At least 1, each with a non-empty name. With `mode: "web_grounding"`, at most 100. With a `locate` question, at most 128 |
| Options per `choice` | 1 to 255 |
| Levels per `score` | 1 to 10 |
| Input tokens | Under 256K for the `state`, its images, and each question. See [Grouping questions](#grouping-questions) |
| Request body | 32 MiB |
| Images | Up to 8 per question, each at most 2,048 tiles of 32 × 32 pixels |
| Web grounding | One search per question. Each search keeps up to 5 results, and the request keeps up to 10 unique URLs as evidence (one per query when there are more than 10 queries). All searches share a 3 second budget. A fetched page adds up to 40,000 characters |

Each organization can send 10 requests per second; per-minute token limits are 15,000,000 for `pplx-decider-v1.3` and `pplx-decider-v1.2` and 4,000,000 for the Flash models. The examples use a 30 second client timeout. See the [API reference](https://docs.perplexity.ai/api-reference/decisions-post.md) for errors, rate limit headers, and the full schema.

## Previous Versions

These models remain supported and take the same request. We encourage you to use the [latest models](#models): `pplx-decider-latest` and `pplx-decider-flash-latest`.

| Model | Parameters | Price (\$/1M input tokens) |
| - | :-: | :-: |
| `pplx-decider-v1.2` | 27B | \$0.02 |
| `pplx-decider-flash-v1.2` | 4B | \$0.01 |
| `pplx-decider-v1-27b` | 27B | \$0.02 |

`pplx-decider-v1.1-27b` is an alias of `pplx-decider-v1-27b` at the same price. These models don't answer `locate` questions.

Before you switch to a newer model, recalibrate your thresholds. The same request can return different probabilities on a different model, so rerun a labeled sample through the new model and pick new cutoffs.

`pplx-decider-v1.2` answers all questions in a request together, and each question sees the others. That helps when the questions are facets of one decision and can hurt when they are independent candidates, such as one question per document; send those in separate requests. `pplx-decider-flash-v1.2` is built for one question per request and answers each question on its own.

## Related Resources

* [Perplexity Decider v1.3: Training, eval, and use cases](https://www.perplexity.ai/hub/blog/perplexity-decider)
