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

# Ornn Inference

> Browse models, check token prices, and chat with a model.

Ornn Inference serves models through offers. Each offer has an API format and separate prices for input, cached input, and output tokens.

Open **Models** to compare offers and copy an API example. **From** shows the lowest price for each token type when offers differ. Open an offer to see its provider, API format, and exact prices. **Compare** shows published benchmark scores for models with results.

Chat Completions offers also let you start a chat. Chat uses your signed-in organization and clears the conversation when you leave or refresh. [Ornn Inference](https://inference.ornn.com).

## Run your first request

Set `ORNN_API_KEY` to a read-write key from the organization you want to use. Paid offers draw from that organization’s Ornn credits. Free offers can run with a zero balance. [Create an API key](https://docs.ornn.com/api-keys.md#create-a-key) · [Credits and charges](#credits-and-charges).

### 1. Find a model

List the available models. Each appears once in `data`. Save the model’s `id`.

```bash theme={null}
INFERENCE_API=https://api.inference.ornn.com/v1
curl --fail-with-body "$INFERENCE_API/models" \
  -H "Authorization: Bearer $ORNN_API_KEY"
```

### 2. Send a message

Replace `publisher/model` with the ID you saved. Ornn selects an active Chat Completions offer, using the lowest input price and then the lowest output price. If both prices tie, the lowest offer UUID wins.

```bash theme={null}
curl --fail-with-body "$INFERENCE_API/chat/completions" \
  -H "Authorization: Bearer $ORNN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "model": "publisher/model",
  "messages": [{"role": "user", "content": "Say hello."}]
}
JSON
```

The reply appears in `choices[0].message.content`.

## Choose an API

Send the public model ID in `model` and match the endpoint to the API format.

| Offer format | Endpoint |
| - | - |
| `chat_completions` | `POST /v1/chat/completions` |
| `responses` | `POST /v1/responses` |
| `messages` | `POST /v1/messages` |
| `decisions` | `POST /v1/decisions` |

### Pin an offer

Use the listing filters to find an offer for the model and format. Prices are decimal strings in USD per million tokens. When the cached-input rate is `null`, the regular input rate applies.

```bash theme={null}
curl --fail-with-body --get "$INFERENCE_API/listings" \
  -H "Authorization: Bearer $ORNN_API_KEY" \
  --data-urlencode 'public_model_id=publisher/model' \
  --data-urlencode 'api_type=chat_completions'
```

Send the offer’s `id` in `X-Ornn-Listing-Id` to pin it. A top-level `provider` field requires a pin. Read one offer with `GET /v1/listings/{listing_id}`. To resolve provider names, pass listing `provider_organization_id` values to `GET https://api.ornn.com/v1/organizations/inference-providers?ids=UUID,UUID`.

Publishers share a logo across models. Fetch it with `GET /v1/publishers/{slug}/logo`.

### Cap token rates

By default, a generation request has no price ceilings. To limit what you pay per million tokens, send any of these headers. You can also pin an offer.

```http theme={null}
X-Ornn-Max-Input-USD-Per-Million-Tokens: 1.50
X-Ornn-Max-Cached-Input-USD-Per-Million-Tokens: 0.30
X-Ornn-Max-Output-USD-Per-Million-Tokens: 6
```

Rates at or below the ceiling qualify, including zero. Use a leading zero for fractions below one, such as `0.5`. When an offer has no separate cached-input rate, Ornn uses its ordinary input rate to check the cached-input ceiling.

> [accordion] SDKs, streaming, and tools
>
> Use `https://api.inference.ornn.com/v1` as the OpenAI SDK base URL. Use `https://api.inference.ornn.com` for the Anthropic SDK, which appends `/v1/messages`. To pin an offer, pass `X-Ornn-Listing-Id` as an extra header. Raw Messages requests accept `x-api-key` or a bearer token.
>
> Chat Completions, Responses, and Messages accept `"stream": true`. Use HTTP/2 when you need to cancel a streaming request promptly. With `curl`, `--http2` requests HTTP/2 over HTTPS.
>
> Responses runs with `store: false` and supports function tools, custom tools, and web search. Send previous turns inline on follow-ups. Use inline content for Responses and Messages.
>
> Decisions takes `input` and one or more predicate, choice, or score questions. It returns `answers` and `usage` in one JSON response. All questions in a call count as one request at the offer’s token rates. [Decisions request format](https://developers.openai.com/api/reference/resources/decisions/methods/create).

> [accordion] Request errors and limits
>
> * `400 invalid_listing_id` means the listing header is malformed or repeated.
> * `400 invalid_price_ceiling` means a price ceiling is malformed or repeated.
> * `404 model_not_found` means no available offer matches the model, format, any pin, and all supplied ceilings. Ornn returns this before starting or charging for the request.
> * `503 inference_pricing_unavailable` means Ornn could not confirm pricing before starting generation. Try again shortly.
>
> Each organization can send 30 generation requests per minute across its keys and Chat. If you get `429`, wait for the delay in `Retry-After` before trying again. Model discovery and request history sit outside that allowance.
>
> Omit both filters from `GET /v1/listings` to see all available offers. Unknown or repeated filters and unsupported formats return `400 invalid_inference_listing_query`.

## CLI and MCP

The Ornn CLI uses your saved login or `ORNN_API_KEY`. Replace `publisher/model` with the public model ID. Add `--listing-id` to pin an offer.

```bash theme={null}
ornn inference completions create \
  --body '{"model":"publisher/model","messages":[{"role":"user","content":"Say hello."}]}' \
  --format json
```

For streaming completions, set `"stream": true` and use `--format human` to receive server-sent events. Press Ctrl-C to close the stream. Discover offers with `ornn inference models list` and `ornn inference listings list`, or run `ornn help inference` for command flags. [Ornn CLI](https://docs.ornn.com/cli.md).

To set price ceilings in the CLI, use `--max-input-usd-per-million-tokens`, `--max-cached-input-usd-per-million-tokens`, or `--max-output-usd-per-million-tokens`.

In MCP, use `inference_models_list` and `inference_listings_list` to find an offer. Call `inference_completions_create` or `inference_decisions_create` with a `body` matching the REST request. Pass `listing_id` to pin an offer. MCP completions return one JSON response, so omit `stream` or set it to `false`. [Connect the MCP server](https://docs.ornn.com/mcp-server.md#connect).

For MCP price ceilings, pass `max_input_usd_per_million_tokens`, `max_cached_input_usd_per_million_tokens`, or `max_output_usd_per_million_tokens` as decimal strings alongside `body`.

To look up one offer or provider through the CLI, use `ornn inference listings show --listing-id ID` or `ornn inference providers list --ids IDS`. MCP exposes the same reads as `inference_listings_show` and `inference_providers_list`.

> [accordion] Read usage and charges from the CLI or MCP
>
> Use `ornn inference requests list` for request history or add `--summary usage --from TIME --to TIME` for totals. Use `ornn inference charges list` to read receipts. All three reads accept a public model ID filter. MCP exposes the same reads in `inference_requests_list` and `inference_charges_list`.
>
> Pass the returned `next_cursor` as `--after` for request and listing pages or `--cursor` for charges. MCP inputs use API field names such as `public_model_id` and `listing_id`.

## Credits and charges

Paid requests require a positive credit balance. An offer is free when its input and output rates are zero and its cached-input rate is zero or unset.

Use **Buy credits** in **Billing** to add funds and **Purchases** to check payment status. Credits post after payment is confirmed. Inference and Compute share your saved card and credit balance.

Ornn charges for reported input and output tokens at the prices saved when the request starts. Charges can appear after the request ends. Concurrent requests can consume more than the available balance before accounting finishes. Additional funding covers the amount owed before more paid requests can start.

Click **Stop** in Chat or press **Ctrl-C** in the CLI to close your stream. If you disconnect over HTTP/1.1, generation can continue, and you may be charged for the full response. Reported usage can still be charged for a failed or cancelled request. A billable request needs reported input and output counts.

> [accordion] Read charge receipts
>
> Charge receipts use the account and billing host, `https://api.ornn.com`. Read-only keys can list your organization’s receipts.
>
> ```bash theme={null}
> curl --fail-with-body --get https://api.ornn.com/v1/ledger/inference-charges \
>   -H "Authorization: Bearer $ORNN_API_KEY" \
>   --data-urlencode 'limit=50'
> ```
>
> The response contains `charges` and `next_cursor`. A receipt includes the request ID, saved usage and rates, and the billed amount in `customer_cents`. Monetary amounts are exact decimal strings in cents. `credit_applied_cents` records the credits applied to that charge when it was recorded. A zero-cost receipt has `customer_cents: "0"` and `ledger_transaction_id: null`.
>
> Filter by exact `public_model_id`, `model_listing_id`, `request_id`, or `provider_organization_id` within your organization’s receipts. RFC 3339 `from` and `to` filter the recorded time, inclusive at the start and exclusive at the end. Results are newest recorded first. Use `limit` from 1 to 500, with a default of 500. Pass `next_cursor` as `cursor` with the same filters. An empty string marks the end.

If you get `402 insufficient_credits`, add credits and try again. If you get `503 billing_unavailable`, retry shortly.

## Request history and usage

**Usage** shows requests, token volume, and cache hit rate by UTC date range, including requests for models since removed from the catalog. **Load more** reads older requests in the selected period.

Use `GET /v1/requests` for the same organization-wide data, including Chat and calls from any of its keys. Read-only keys can use this endpoint. Replace the example dates with your window.

```bash Request history theme={null}
curl --fail-with-body --get https://api.inference.ornn.com/v1/requests \
  -H "Authorization: Bearer $ORNN_API_KEY" \
  --data-urlencode 'from=2026-11-10T00:00:00Z' \
  --data-urlencode 'to=2026-11-11T00:00:00Z' \
  --data-urlencode 'limit=50'
```

```bash Usage totals theme={null}
curl --fail-with-body --get https://api.inference.ornn.com/v1/requests \
  -H "Authorization: Bearer $ORNN_API_KEY" \
  --data-urlencode 'summary=usage' \
  --data-urlencode 'from=2026-11-10T00:00:00Z' \
  --data-urlencode 'to=2026-11-11T00:00:00Z'
```

Filter either view by the saved `public_model_id`, `model_listing_id`, or both. Use `request_id` to look up the request on a receipt. RFC 3339 dates filter when requests started, inclusive at `from` and exclusive at `to`. History returns `data` newest first, with `limit` from 1 to 100 (default 50). Pass `next_cursor` as `after` with the same filters until the cursor is `null`.

Totals require both dates within 90 days of each other. They return one `by_model` row per model and one `days` row per UTC day with requests, oldest first. Omit pagination parameters for totals.

> [accordion] Read status, token counts, and timings
>
> A request records its saved model ID and rates, reported token counts, timestamps, and a status of `running`, `completed`, `failed`, or `cancelled`. Chat calls have `api_key_id: null`. Cancellation records a disconnect before completion or failure, with the time in `cancelled_at`.
>
> `upstream_http_status` records the HTTP status Ornn received from the provider. A stream can open with `200` and later fail or be cancelled. The field is `null` while the request is running, for older requests, or when Ornn receives no response headers.
>
> Input totals already include cached input. An unreported count is `null` on an individual request, and reported zero stays zero. The summary counts requests with input and output usage under `requests_with_usage` and requests with cached usage under `requests_with_cached_usage`. It includes reported counts for failed and cancelled calls. An empty period returns zero totals and an empty `by_model`.
>
> `first_output_ms` measures the time from upstream dispatch to the first streamed output. It is `null` when there was no streamed output. `duration_ms` ends when Ornn finishes reading, encounters an error, or closes on disconnect. Both measurements include network and queue time and can be `null` on older requests.
>
> The by-model summary reports `median_first_output_ms` and `median_output_tokens_per_second` for completed requests. Output rate uses `output_tokens × 1000 / duration_ms`, including the wait for first output. The sample counts are `completed_requests_with_first_output` and `completed_requests_with_output_rate`. Missing measurements and zero durations are excluded from the relevant median.

## Serve models as a provider

Provider access scopes listings, requests, and earnings to your organization. The provider portal shows earnings and token counts by model for a UTC date range of up to 90 days. [Provider earnings](https://provider.ornn.com/earnings).

> [accordion] Manage provider listings
>
> Use `GET /v1/provider/listings` to list your offers, or `GET /v1/provider/listings/{listing_id}` to inspect one. Create with `POST /v1/provider/listings` and update with `PATCH /v1/provider/listings/{listing_id}`. Writes require a read-write key.
>
> List catalog models with `GET /v1/provider/models`. Create a listing with its `public_model_id`, your `upstream_url` and `upstream_model`, and the `api_type` the endpoint serves. Set prices as decimal strings in the `provider_*_usd_per_million_tokens` fields. New listings start inactive. An optional `upstream_credential` is write-only.
>
> Test the upstream endpoint, then set `active: true` to publish. Set `LISTING_ID` to the offer UUID and use a provider read-write key. Check the public listing after publishing.
>
> ```bash theme={null}
> curl --fail-with-body -X PATCH "$INFERENCE_API/provider/listings/$LISTING_ID" \
>   -H "Authorization: Bearer $ORNN_API_KEY" \
>   -H 'Content-Type: application/json' \
>   -d '{"active":true}'
>
> curl --fail-with-body "$INFERENCE_API/listings/$LISTING_ID" \
>   -H "Authorization: Bearer $ORNN_API_KEY"
> ```
>
> The public read returns `200` with the offer’s prices once the listing is active and has both input and output prices. The listing's `model_id` stays the same across model renames.
>
> In the CLI, use `ornn inference provider listings` with `list`, `show`, `create`, or `update`. Pass `--listing-id` for show or update and `--body JSON` for writes. MCP exposes these actions as `inference_provider_listings_*` tools and accepts a `body` object for writes.

> [accordion] Read usage for your models
>
> Use `GET /v1/provider/requests` to read requests served by your listings, including inactive listings. Read-only keys can use the same model and date filters, pagination, and `summary=usage` as customer request history.
>
> In **Usage** in the provider portal, choose a listing or search by request ID. Failure rate is failed requests divided by all requests. The CLI command is `ornn inference provider requests list`. In MCP, use `inference_provider_requests_list`.

> [accordion] Read provider earnings
>
> Use `GET /v1/ledger/inference-charges?view=provider` on `https://api.ornn.com` with a provider organization key. The view accepts read-only keys and the same model, request, recorded-time, and pagination filters as charge receipts. The credential supplies the organization.
>
> Receipts include gross `customer_cents`, net `provider_cents`, `fee_cents`, saved usage and rates, and `usage.transaction_fee_ppm`. Amounts are exact decimal strings in cents.
>
> For totals, add `summary=daily` and RFC 3339 `from` and `to` within 90 days. The response groups the three amounts into UTC `days` and `by_model`. Model rows also show input, cached input, and output counts, ordered by net earnings. An empty range returns empty arrays. Omit `limit` and `cursor` for totals.
>
> In the CLI, run `ornn inference charges list --view provider`. Add `--summary daily --from TIME --to TIME` for daily totals.


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