> For the complete documentation index, see [llms.txt](https://docs.tensorx.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tensorx.ai/api-reference/logprobs.md).

# Logprobs

Get the log probability of each token the model generates.

Log probabilities (logprobs) show how likely the model considered each token that it generated. Use them to measure how confident the model is in an answer, to score classification labels or to find the parts of a response where the model was unsure.

Most chat completion models support logprobs. Embedding and audio models do not.

***

## Request Parameters

| Parameter      | Type    | Default | Description                                                                              |
| -------------- | ------- | ------- | ---------------------------------------------------------------------------------------- |
| `logprobs`     | boolean | `false` | Return the log probability of each output token                                          |
| `top_logprobs` | integer | -       | Also return the most likely tokens at each position (0 to 20). Requires `logprobs: true` |

***

## Basic Usage

The examples on this page use `deepseek/deepseek-v4.1-flash-1017`. Replace it with any model that supports logprobs.

{% tabs %}
{% tab title="Python" %}

```python
import math
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.tensorx.ai/v1"
)

response = client.chat.completions.create(
    model="deepseek/deepseek-v4.1-flash-1017",
    messages=[{"role": "user", "content": "What is the capital of France? Answer in one word."}],
    logprobs=True,
    top_logprobs=3
)

for item in response.choices[0].logprobs.content:
    print(f"{item.token!r}: {math.exp(item.logprob):.1%}")
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.tensorx.ai/v1'
});

const response = await client.chat.completions.create({
  model: 'deepseek/deepseek-v4.1-flash-1017',
  messages: [{ role: 'user', content: 'What is the capital of France? Answer in one word.' }],
  logprobs: true,
  top_logprobs: 3
});

for (const item of response.choices[0].logprobs.content) {
  console.log(`${JSON.stringify(item.token)}: ${(Math.exp(item.logprob) * 100).toFixed(1)}%`);
}
```

{% endtab %}

{% tab title="curl" %}

```bash
curl https://api.tensorx.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TENSORX_API_KEY" \
  -d '{
    "model": "deepseek/deepseek-v4.1-flash-1017",
    "messages": [{"role": "user", "content": "What is the capital of France? Answer in one word."}],
    "logprobs": true,
    "top_logprobs": 3
  }'
```

{% endtab %}
{% endtabs %}

This model does not reason by default. If you use a model that does, see [Reasoning Models](#reasoning-models).

***

## Response Format

Each choice carries a `logprobs` object. Its `content` array has one entry for each output token:

```json
{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Paris"
      },
      "logprobs": {
        "content": [
          {
            "token": "Paris",
            "bytes": [80, 97, 114, 105, 115],
            "logprob": -4.768372718899627e-07,
            "top_logprobs": [
              { "token": "Paris", "bytes": [80, 97, 114, 105, 115], "logprob": -4.768372718899627e-07 },
              { "token": "The", "bytes": [84, 104, 101], "logprob": -15.375000953674316 },
              { "token": " Paris", "bytes": [32, 80, 97, 114, 105, 115], "logprob": -16.25 }
            ]
          },
          {
            "token": "<｜end▁of▁sentence｜>",
            "bytes": [60, 239, 189, 156, 101, 110, 100, 226, 150, 129, 111, 102, 226, 150, 129, 115, 101, 110, 116, 101, 110, 99, 101, 239, 189, 156, 62],
            "logprob": -0.0002960720448754728,
            "top_logprobs": [
              { "token": "<｜end▁of▁sentence｜>", "bytes": [60, 239, 189, 156, 101, 110, 100, 226, 150, 129, 111, 102, 226, 150, 129, 115, 101, 110, 116, 101, 110, 99, 101, 239, 189, 156, 62], "logprob": -0.0002960720448754728 },
              { "token": ".", "bytes": [46], "logprob": -8.125295639038086 },
              { "token": "\n\n", "bytes": [10, 10], "logprob": -16.500295639038086 }
            ]
          }
        ]
      },
      "finish_reason": "stop"
    }
  ]
}
```

| Field                        | Type   | Description                                                                                                            |
| ---------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
| `choices[].logprobs.content` | array  | One entry for each output token, in order                                                                              |
| `content[].token`            | string | The token text                                                                                                         |
| `content[].logprob`          | number | The natural log of the token's probability                                                                             |
| `content[].bytes`            | array  | The UTF-8 bytes of the token                                                                                           |
| `content[].top_logprobs`     | array  | The most likely tokens at this position, each with `token`, `logprob` and `bytes`. Present when you set `top_logprobs` |

To turn a logprob into a probability, take its exponential: `math.exp(logprob)` in Python or `Math.exp(logprob)` in JavaScript. A logprob of `0` means that the model was certain. A logprob of `-0.69` is about 50% and `-2.3` is about 10%. In the example, the model gave `Paris` a probability above 99.99%. The next most likely first token, `The`, has a logprob of about `-15.4`, which is close to zero.

The last entry, `<｜end▁of▁sentence｜>`, is the model's end-of-turn token. See [The Last Entry Can Be a Stop Token](#the-last-entry-can-be-a-stop-token).

***

## Example: Confidence Threshold

A common use is to let a workflow act on its own when the model is sure, and to send the case to a person when it is not. This example checks whether an invoice is a duplicate:

```python
import math
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.tensorx.ai/v1"
)

def check_invoice(new_invoice, paid_invoices):
    response = client.chat.completions.create(
        model="deepseek/deepseek-v4.1-flash-1017",
        messages=[
            {"role": "system", "content": "You check supplier invoices. Answer with one word: yes or no."},
            {"role": "user", "content": f"Paid invoices:\n{paid_invoices}\n\nNew invoice:\n{new_invoice}\n\nIs the new invoice a duplicate?"}
        ],
        max_tokens=1,
        temperature=0,
        logprobs=True,
        top_logprobs=5
    )

    # Add up the probability of each form of the answer, such as "Yes", " yes" and "yes".
    first = response.choices[0].logprobs.content[0]
    probs = {}
    for alt in first.top_logprobs:
        word = alt.token.strip().lower()
        probs[word] = probs.get(word, 0.0) + math.exp(alt.logprob)
    p_yes = probs.get("yes", 0.0)

    if p_yes >= 0.95:
        return "hold", p_yes      # Almost certainly a duplicate
    if p_yes <= 0.05:
        return "pay", p_yes       # Almost certainly new
    return "review", p_yes        # Unsure: send to a person

paid = "INV-1042, Acme Ltd, 2026-09-30, EUR 1,250.00, office chairs"
print(check_invoice("INV-1042, Acme Ltd, 2026-09-30, EUR 1,250.00, office chairs", paid))
print(check_invoice("INV-1187, Acme Ltd, 2026-10-21, EUR 310.00, desk lamps", paid))
print(check_invoice("INV-1042-A, Acme Ltd, 2026-10-02, EUR 1,250.00, office chairs (corrected address)", paid))
```

Set the two thresholds from your own data. For example, run the check over invoices that a person has already reviewed and pick the values where the automatic decisions were correct.

***

## Streaming

With `stream: true`, each chunk carries the logprobs for the tokens in that chunk:

```python
import math
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.tensorx.ai/v1"
)

stream = client.chat.completions.create(
    model="deepseek/deepseek-v4.1-flash-1017",
    messages=[{"role": "user", "content": "Name three primary colours."}],
    stream=True,
    logprobs=True
)

tokens = []
for chunk in stream:
    if not chunk.choices:
        continue  # The final usage chunk has no choices
    logprobs = chunk.choices[0].logprobs
    if logprobs and logprobs.content:
        tokens.extend(logprobs.content)

lowest = min(tokens, key=lambda t: t.logprob)
print(f"{len(tokens)} tokens. Least certain: {lowest.token!r} at {math.exp(lowest.logprob):.1%}")
```

***

## Things to Know

### Reasoning Models

When a model reasons before it answers, `logprobs.content` covers the reasoning tokens as well as the answer. The entries for the reasoning come first, then the end-of-reasoning marker (`</think>` on GLM models), then the answer.

The reasoning also uses the `max_tokens` budget. With a small `max_tokens`, such as the single token in the confidence example, the budget runs out before the answer starts.

Turn thinking off when you need logprobs for the answer only. The control differs by model family. See [Reasoning](https://docs.tensorx.ai/api-reference/reasoning.md).

### The Last Entry Can Be a Stop Token

The last entry in `logprobs.content` can be the token that ended the model's turn, such as `<｜end▁of▁sentence｜>` or `<|user|>`. The token depends on the model. It is not part of `message.content`. Leave it out when you score an answer.

### Tokens Are Pieces of Words

A token is often part of a word, and the same word can come back in different forms, such as `yes`, `yes` or `Yes`. Normalise the tokens and add up their probabilities before you compare them, as the confidence example does.

### Values Depend on the Deployment

The values can differ from the same model on another platform, because of the model's [quantisation](https://docs.tensorx.ai/api-reference/quantisation.md) and serving configuration. They can also change when TensorX updates a model's deployment. Set thresholds from TensorX responses, not from values measured elsewhere, and check them again after a model update.

### Check Before You Read

A model that does not support logprobs does not return them. Check that `choices[].logprobs` is present before you read it.

***

## See Also

* [Chat Completions](https://docs.tensorx.ai/api-reference/chat-completions.md) - Full API reference
* [Streaming](https://docs.tensorx.ai/api-reference/streaming.md) - Streaming responses
* [Reasoning](https://docs.tensorx.ai/api-reference/reasoning.md) - Thinking controls by model family
* [Quantisation](https://docs.tensorx.ai/api-reference/quantisation.md) - Deployment precision


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.tensorx.ai/api-reference/logprobs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
