# Choosing a provider

> Use Auto routing or choose a published computer and model offer at a price you have reviewed.

Choose an [enabled model edition](https://router.optimai.network/docs/models-and-availability.md) first. Then let Router select eligible capacity with Auto, or select one published computer/model offer yourself.

## Auto or a specific offer

| Choice         | Behavior                                                                                                                                                  |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Auto · default | Omit `provider_selection`. Router chooses eligible available capacity with the lowest conservative credit reservation; equal rounded reservations rotate. |
| Specific offer | Send its `offer_id` and displayed `pricing_revision`. Router accepts only that computer/model offer at that revision.                                     |

Auto uses saved input/output rates, the provider's context bound, and your output limit to calculate a conservative maximum, rounded up to six decimal credits. This is a reservation, not a prediction of the final charge or a ranking by only one displayed rate. The offer must fit your authorized request maximum. Public publication is not required for Auto eligibility.

```mermaid
flowchart LR
  accTitle: Auto and manual provider selection
  accDescr: For the exact model, Auto ranks eligible conservative reservations and manual selection binds the chosen offer and price revision. Eligibility and capacity checks lead to an accepted saved quote or an explicit error, without silent fallback.
  Auto[Auto routing] --> Check[Eligible capacity]
  Manual[Chosen offer] --> Check
  Check -->|Pass| Accept[Accept quote]
  Check -->|Fail| Error[Explicit error]
```

## Discover public offers

In [Playground](/dashboard/playground), open the provider picker for your selected model. You can also follow a public provider page at `/providers/{handle}`. Names, descriptions, websites, and avatars are self-described identities; they do not establish verified reputation, confidential execution, or guaranteed performance.

For an API integration, query discovery at the API origin, outside `/v1`:

```bash
curl --get "${ROUTER_BASE_URL%/v1}/public/provider-offers" \
  --data-urlencode 'model=gemma3:1b'
```

The response includes `offers`, `has_more`, and `next_cursor`. Review each offer's public computer name, exact model, separate input/output rates in USD per 1M tokens, `availability`, and `pricing_revision`. Pass `next_cursor` as `cursor` to load more; a null cursor ends the list. Available offers precede busy and offline offers within each page. Discovery observes capacity and does not reserve it.

## Send your selection

Copy the current offer UUID and pricing revision into the [chat request](https://router.optimai.network/docs/api/chat-completions.md#select-a-specific-provider):

```json
{
  "model": "gemma3:1b",
  "messages": [{ "role": "user", "content": "Explain retrieval briefly." }],
  "max_tokens": 128,
  "provider_selection": {
    "offer_id": "00000000-0000-4000-8000-000000000001",
    "pricing_revision": 3
  }
}
```

The UUID and revision above are synthetic. Use values returned by discovery. Keep the usual authentication, `Idempotency-Key`, and spending limit headers. You cannot serve your own account's paid requests.

API selection applies to each request. Playground selection lasts for its current conversation. Omitting `provider_selection` explicitly selects Auto.

## Recover deliberately

Router checks the published profile and offer, ownership, exact model revision, current price, and capacity before acceptance. It never silently switches a manual selection to Auto or another offer.

| Error                           | Next step                                                                        |
| ------------------------------- | -------------------------------------------------------------------------------- |
| `provider_price_changed`        | Fetch the current offer and review its price before accepting the new revision.  |
| `provider_offer_unavailable`    | Choose another published eligible offer or explicitly choose Auto.               |
| `selected_provider_unavailable` | Wait for the selected computer, choose another offer, or explicitly choose Auto. |
| `self_provider_only`            | Choose an offer owned by another account.                                        |

Changing the offer, pricing revision, or routing choice creates a new logical request and needs a new UUID. If an earlier result is uncertain, check its credit receipt first; retries of that request keep the original UUID and unchanged body. See [retries and cancellation](https://router.optimai.network/docs/retries-and-timeouts.md).

> **Accepted quotes stay fixed**
> Once accepted, later price changes or unpublishing do not change that request's saved quote. Interrupted work may still charge for accepted provider-reported usage. Token counts are not independently verified; the receipt records settlement.

See the [provider API reference](https://router.optimai.network/docs/api/providers.md) for discovery fields and the [privacy guide](https://router.optimai.network/docs/security-and-privacy.md) for the provider trust boundary.