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

# Credits

> The price per million tokens, what counts as input and output for each call, what is never charged, and what happens when credits run out.

This page explains how Priors charges for use. After you read it, you can estimate the cost of a call, read your balance, and know what happens when the balance is zero.

Your organization has one balance of **credits**. Calls that make the agent learn or answer take credits from this balance. Calls that only read data are free. You can read the balance and every charge at any time.

## The price

The price is per one million tokens.

| | Input | Output |
| - | - | - |
| Every call | 10,000 credits | 10,000 credits |

Input and output have the same price. There is no separate price per model, plan, or feature. Your organization can have a different price by agreement. The `cost` field on each charge is the exact amount that was charged.

## What counts as input and output

The table below says what is counted for each call.

| Call | Input | Output |
| - | - | - |
| `observe` | The text of every observation you send. | Nothing. |
| `observe-file` | The text of every piece the document was split into. | Nothing. |
| `observe-and-enrich` | The text of every observation you send. | The `response_context` you receive. |
| `observe-and-respond` | The text of every observation you send. | The `response_context` you receive. |
| `chat`, `chat/stream` | The `message` you send. | The `message` you receive. |

The memories that the agent reads to answer are not counted. You pay for what you send and what you receive.

## How tokens are counted

Priors counts the words in the text and multiplies by 1.3. One English word is about 1.3 tokens. You do not need a tokenizer.

```text theme={null}
tokens = words × 1.3
cost   = tokens × 0.01 credits
```

So:

* 1,000,000 tokens cost 10,000 credits.
* 1 word costs 0.013 credits.
* 1,000 words in and 1,000 words out cost 26 credits.

## What is never charged

* Creating, reading, changing, and deleting agents and threads.
* Listing anything. Polling a status. Reading the balance.
* A request that fails. If the response is an error, nothing is charged.
* A file that is refused: too large, password protected, unsupported, or a duplicate of a file this thread already has.
* A request you send again with the same `request_id` (or the same `turn_id` on `chat`). It is charged once.
* A message or file piece that could not be learned. The input side is refunded, and `refunded_credits` on the learning report says how much. An answer that Priors wrote and delivered stays charged.
* Learning that a Priors restart paused. It resumes with nothing charged again.
* The part of a stopped upload that was already learned. Finishing it with `finish-learning` charges only what is left.

## Examples

| Request | Input words | Output words | Credits |
| - | - | - | - |
| `observe`, one message of 40 words | 40 | 0 | 0.52 |
| `observe`, 100 messages of 40 words in one call | 4,000 | 0 | 52 |
| `observe-file`, a handbook of 9,000 words | 9,000 | 0 | 117 |
| `observe-and-respond`, a question of 12 words, an answer of 60 words | 12 | 60 | 0.94 |
| `chat`, a message of 25 words, an answer of 300 words | 25 | 300 | 4.23 |
| One month with 5,000 chat messages of the size above | | | about 21,000 |

## When a charge happens

1. Before the request runs, Priors checks that the balance is above zero.
2. The request runs.
3. If the request succeeded, Priors writes the cost to the ledger.

The request that takes the balance to zero or below still completes. The next request that costs credits is refused. An organization that has no balance yet is refused in the same way.

## When the balance is zero

Every request that costs credits returns `402`:

```json theme={null}
{"error": "No more credits", "code": "payment_required", "request_id": "req_01J..."}
```

* Free calls still work: list agents, read threads, poll a status, read the balance.
* Nothing is deleted or paused. The memory stays.
* After you add credits, the same requests succeed again. Nothing else changes.

To avoid a `402` in front of a user, watch `low_credit_threshold` (see below) and warn the user early.

## Read the balance and the charges

```bash theme={null}
curl "https://app.sapientpriors.com/api/v1/billing?limit=20" \
  -H "Authorization: Bearer $SP_API_KEY"
```

```json theme={null}
{
  "organization_id": "org_01J...",
  "enabled": true,
  "balance": "842.37",
  "low_credit_threshold": "100",
  "entries": [
    {"entry_id": 9184, "route": "chat", "in_words": 25, "out_words": 300, "cost": "4.225", "created_at": "2026-09-17T11:02:14Z"},
    {"entry_id": 9183, "route": "observe_file", "in_words": 9000, "out_words": 0, "cost": "117", "created_at": "2026-09-17T10:40:03Z"}
  ],
  "next_cursor": 9183
}
```

| Field | Meaning |
| - | - |
| `balance` | The credits left, as an exact decimal string. `null` means no balance was set up yet. |
| `low_credit_threshold` | Show a warning when `balance` is below this value. It does not block anything. |
| `entries` | The charges, newest first. `route` names the call. `in_words` and `out_words` are the counted words. |
| `next_cursor` | Send it as `before` to read the next page. |
| `enabled` | `false` means credits are not switched on for your organization. Nothing is charged. |

Any key of your organization can read this. `503 service_unavailable` means the ledger did not respond; wait, then try again. This call works when the balance is zero.

## How to keep costs predictable

* Send `detail: brief` on answering calls when a short answer is enough. It lowers the output side without cutting the text.
* Set `max_context_chars` when you need a hard limit. It caps the output side by trimming the text.
* Send old messages in `observe` calls of up to 100 observations. The price is the same, and you make fewer calls.
* Upload each document once. A duplicate is free, and a duplicate from another thread is refused rather than charged. A file exported again with different bytes is a new document.
* Count the words before you send. The input cost is `words × 0.013`.


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