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

# Usage and request history

> See what your requests used and cost, and look up a single request.

Your organisation's usage shows what its requests used and cost. Its request history helps you diagnose a single request. Read the last 7 days of usage:

```bash theme={null}
curl --fail-with-body 'https://api.sqwish.ai/v1/organization/usage?days=7' \
  -H "Authorization: Bearer $SQWISH_API_KEY"
```

`GET /v1/organization/usage` returns `totals`, the same totals for the period before in `previous`, and `daily` values. `by_model` and `by_api_key` break them down by served model and by API key. Dates are UTC unless you pass a `timezone`. [Diagnose a request](#diagnose-a-request) lists the fields.

In an organisation with several [projects](https://docs.sqwish.ai/guides/projects.md), a key that works as a developer sees only its own project. It lists, spends and counts usage there alone. This holds for an owner's full-access key too. To read usage for the whole organisation, use an [admin key](https://docs.sqwish.ai/guides/organisations.md#admin-keys).

## Metering

`usage.input_tokens` counts your input with the shared billing tokenizer, which `usage.tokenizer` names. It is not the model's rendered prompt. `usage.decisions` counts the decisions. Native decisions return probabilities, not generated text.

### What counts as input

You pay only for the text you send:

* the `context`
* each decision's `question`
* each outcome's name and description. A binary decision counts only the descriptions you give `yes` and `no`. An ordinal decision counts its levels and its `rubric` lines
* the image tokens of each picture ([images](https://docs.sqwish.ai/guides/images.md#billing))

A decision whose outcomes are the same as an earlier decision's in the request, with the same names and descriptions in the same order, doesn't pay for them again. Nothing OneHot adds to a request is billed. The [quickstart](https://docs.sqwish.ai/quickstart.md)'s request, with its descriptions and rubric, comes to 648 input tokens. To count a request before you send it, use its estimate, `POST /v1/decide/estimate` ([score many texts](https://docs.sqwish.ai/guides/scale.md#price-it-first)).

Usage is metered against the model that answers, a fallback included. Each billed input token costs:

| Answering model | Price per billed input token |
| - | - |
| A base model | `decision_price_nano` in its catalogue entry, in nano-USD |
| A fine-tuned model | `pricing.tuned_multiplier` times its base size's price, unless its catalogue entry shows a price of its own. The standard [prices](https://docs.sqwish.ai/guides/pricing.md) show the result |
| A fallback | Its own price or the requested model's, whichever is lower. A fallback never costs more than the model you asked for |

Before a decision runs, the wallet reserves the requested model's price ([Credit and holds](https://docs.sqwish.ai/guides/billing.md#credit-and-holds)). The response's `charge` records the operation ID, the reserved amount and the answering model's charge.

The charge and the answer are saved together before the answer is returned. To recover the answer after a lost response, send the request again with its `Idempotency-Key` ([After a lost response](https://docs.sqwish.ai/guides/retries.md#after-a-lost-response)). An organisation with [zero data retention](https://docs.sqwish.ai/guides/zero-data-retention.md) keeps no answer. There, a retry runs again and is charged again.

Read prices from the current catalogue and account, not from a guide.

## Diagnose a request

```bash theme={null}
SQWISH_USAGE_DAY=$(date -u +%F)
curl --fail-with-body "https://api.sqwish.ai/v1/organization/usage/requests?start=$SQWISH_USAGE_DAY&end=$SQWISH_USAGE_DAY&limit=25" \
  -H "Authorization: Bearer $SQWISH_API_KEY"
```

`start` and `end` are required. They are inclusive dates, in UTC unless you pass a `timezone`. This example reads today in UTC. The history is cursor-paginated ([Pagination](https://docs.sqwish.ai/guides/requests.md#pagination)). To find one request, pass `request_id`: the `X-Request-ID` or `X-Operation-ID` its response carried.

A period is 1 to 90 days. A page lists `limit` requests: 25 if you leave it out, and at most 200. `model`, `api_key_id`, `source` (`api` or `console`) and `project` narrow it to one model, key, source or project. `GET /v1/organization/usage` takes the same filters, and its `days` is 1 to 90, or 30 if you leave it out.

The history has request IDs, status codes, requested and served models, timing, token counts, fallback reasons, costs and key identity. It never has the request's context or answers. Fields can be null for a failure before scoring.

`GET /v1/organization/usage` reports:

| Field | What it counts |
| - | - |
| `requests` | Successful metered requests |
| `total_requests` | Requests including recorded 4xx and 5xx failures |
| `decisions`, `input_tokens` | The decisions asked in successful requests, and their billed input tokens |
| `errors_4xx`, `errors_5xx` | Requests that failed, by kind of status |
| `fallbacks` | Successful requests that [another model](https://docs.sqwish.ai/guides/models-and-fallback.md) answered |
| `cost_usd` | What the requests cost, as an exact [USD amount](https://docs.sqwish.ai/guides/billing.md#usd-amounts) |
| `p50_ms`, `p95_ms` | Inference-stage time, from histogram buckets |
| `request_ms_sum`, `request_ms_count` | Full server-request time where measured. Divide them for the average |
| `laboratory` | Fine-tunes, prompt-tuning jobs, evaluation predictions, keep warm and dataset storage, each dated by the day its work started. It ignores the model, key and source filters |

The other fields count inference. None of the times includes the client's network time.


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