Choosing a sharer

By default the router picks for you: cheapest first, ties broken by health. When you want a say, there are these levers: headers on one request, the same settings kept on a key, a cost cap per request, a preference for speed over price, and named routes with their own order, limits and budgets.

The headers

1x-aile-max-price: 8
2x-aile-provider: claude
3x-aile-verified: 1
4x-aile-data-collection: deny

The old names x-aile-lender and x-aile-exclude-lender still work.

Capping price

Two forms:

1x-aile-max-price: 8      # $8 per million tokens, absolute
2x-aile-max-price: 80%    # 80% of this model's published rate (higher of in/out)

The percentage form needs a model in the body to have a rate to be a percentage of; a model with no published list price is refused with a 404 before the percentage is read. A malformed value is a 400 rather than a silently ignored header.

The cap is checked against the quote that will bill, on every failover attempt. Past a model's long-context line the whole request bills at the long-context rate, so a long prompt is compared against that rate, self-hosted models included. If the provider reports a prompt past a line the estimate did not reach, a dollar cap still bounds the bill: no input or output token bills above it. A percentage is of the band's own list, so that band bills in full.

A price floor

1x-aile-min-price: 20%

A sharer priced under 20% of the model's list (more than 80% off), on input or output, is skipped and the next one serves. It is the key's Max discount slider. Use it when the cheapest sharer is too cheap to trust. Like the ceiling it needs a priced model, binds the token-priced endpoints only, and is checked again on the quote that bills, so a sharer who lowered its price after being chosen is passed over too. A header can raise the key's floor, never lower it, and a key's floor cannot sit above its own discount limit.

When the floor leaves nobody for a model the answer is a 503: "every sharer online for <model> is priced more than 80% below list", naming where the floor lives (the key or the header).

Capping the cost of a request

x-aile-max-price caps the rate. A cost cap caps the request: the most one request may be charged, in dollars.

1x-aile-max-cost: 0.50

It can be set in three places, and the lowest binds:

• the x-aile-max-cost header, on any request, with or without a key;
• the key's Max cost per request on its Routing button (stored as "maxCostUsd");
• a route target's own Max cost per request.

A header or a target can only lower the key's cap. The value is dollars above 0 and at most 10,000, with at most 6 decimals; a leading $ is accepted. Anything else is a 400, never a header quietly ignored.

On chat:

• The request is sent the output cap it is priced at. A body that names no max_tokens is sent 4096, so the answer cannot run past what was quoted.

• A sharer whose quote for the request is above the cap is passed over and the next one is tried, before anything is held or any payment is checked. A cheaper sharer serves; a dearer one is never paid to.

• When every sharer quotes above it, the answer is a 402 naming the cheapest quote and the cap, and you were not charged. In a named route the route moves on to its next target instead, which may be cheaper.

• You are never charged more than the cap. If the provider reports more usage than was quoted (a cache write, a longer prompt than estimated), you are billed the cap and the sharer absorbs the rest.

• A request whose answer the output cap cannot bound is refused with a 400 naming the cap, before anything is held, as a request paid with x402 is:

  • n other than 1 (the quote prices one choice);
  • a self-hosted request carrying the runtime's own n_predict or n_cmpl;
  • a provider that sends no output cap upstream, such as codex;
  • an endpoint with no output cap field;
  • a provider that adds a thinking budget or tool floor on top of max_tokens, found once the request to that provider is built.

  In a named route the route moves on to its next target instead, whose provider may bound it. Send the request without a cost cap to have it served.

• A request that declares a server-side tool the provider bills on its reported usage (hosted_tools on /v1/models, such as Grok's x_search) is refused with a 400 under a cap: nothing could bound what those tool results add.

• A stake key whose fallback key carries a cost cap brings that cap whenever the fallback pays. Which key pays is decided only once the request is held, so such a key's requests are always sent the output cap they are priced at, also when the free window pays. The fallback's cap refuses a request only when the fallback pays.

On the non-chat endpoints the cap is checked against what the request would hold, before anything is held: a per-unit endpoint's exact price, a ceiling where the bill is counted afterwards (rerank, OCR pages). Above the cap it is a 402. Embeddings bill the reported tokens, capped at the cap. Decisions hold a whole context window per question, so most cost caps refuse them.

A request paid with x402 honours the header too: the 402 asks for payment to a sharer quoting under the cap, and when none does it is a plain 402 with no payment document, so your client does not sign a payment that would only be refused again.

Calling an agent's tool (POST /mcp/call, or use_agent_tool over MCP) honours the cap too: a call priced above the key's cap, the x-aile-max-cost header or a stake key's fallback's cap is a 402, before the sharer is called or anything is charged. The MCP model tools (use_model, generate_image and the rest) do not pass your session's x-aile-max-cost on, so there only the key's own cap applies.

A cost cap chooses no sharer: it does not affect the stake-funded discount.

Block or allow sharers

A sharer that keeps failing can be routed around on every model at once:

1x-aile-exclude-sharer: L1a2b3c4d5e6f7a8b
2x-aile-sharer: L1a2b3c4d5e6f7a8b,L9f8e7d6c5b4a3f2e

The first skips that sharer and the next one serves. The second allows only the listed sharers, cheapest of them first. On a key they are Never these sharers and Only these sharers, under Sharers on its Routing button, and the /market order book's Block on a key / Allow on a key writes them for you. A key can also carry Never these providers, under Providers: a model on one of them is refused with a 400 before anything is held. Self-hosted is not a provider here: untick Allow self-hosted model instead.

Sharers are named by the handle on their marketplace card (L + 16 hex, read in any case), up to 50 per list; up to 50 providers too. The lists cover the whole key: every plain request, every target of every route, and any-provider requests, so a route target cannot carry its own. Price order is unchanged: among the sharers a list leaves, the cheapest still goes first.

A request can only narrow them. x-aile-exclude-sharer and x-aile-exclude-provider add to the key's lists, and x-aile-sharer naming several picks among the key's allowed sharers. Naming a sharer the key blocks, or one outside its allowed sharers, is a 400. A list header longer than 4 KiB is a 400 too.

When a list leaves nobody for a model, the answer says so with a 503: "every sharer online for <model> is blocked by this API key" (or "by x-aile-exclude-sharer", when the header did it), or "none of this API key's allowed sharers (…) has a machine online and sharing <model> right now". The error body's refusedBy names the header the list belongs to. A model on an excluded provider is a 400: "this API key excludes provider <provider>".

The lists and the routes are checked against each other when either is saved: a key cannot exclude a provider one of its routes targets, nor block, or leave off its allowed sharers, a sharer a route target is pinned to. A sharer both allowed and blocked is refused, and so is an allowed list beside the single Sharer handle pin. Change or remove that route first.

Any provider for a bare model

Every model normally names its provider (claude/claude-sonnet-5). Write auto/ instead of a provider and any provider that sells the model may serve it:

1{ "model": "auto/claude-sonnet-5", "messages": [{ "role": "user", "content": "hi" }] }

• every provider whose catalogue lists that id (or an id ending in it, such as OpenRouter's anthropic/claude-sonnet-5), and that speaks the endpoint you posted to, is a candidate, and a version's dot and dash count as one spelling, so auto/claude-sonnet-5-5 also finds Copilot's claude-sonnet-5.5;
• candidates are tried cheapest first, at most six, and a candidate that cannot serve falls through to the next;
• a self-hosted model is never chosen, and your own capacity is never a candidate;
• x-aile-provider: claude,openrouter (a comma list) limits the candidates; x-aile-provider: any with a bare id is the same as auto/, and one provider in the header beside auto/ is a 400, since the two name different things;
• x-aile-exclude-provider: kiro, or the key's Never these providers, takes providers out (and refuses a request that names one directly);
• what follows auto/ is a bare id: auto/claude/claude-sonnet-5, auto/local/llama3 or auto/ alone is a 400;
• a key limited to one provider cannot be widened (400), nor can x-aile-capacity: local be added (400);
• it needs an API key and works on the three chat endpoints only. A route target names its own provider, so auto/… cannot be one (saving it is refused), and under a key's own route it is a 400.

The key's own settings apply to every candidate: max price, price floor, cost cap, sharer lists, speed first and moving failing sharers back. A route's order, first-token limit, daily budget and Prefer do not, since there is no named route. The six are chosen among the sharers your sharer lists, a single sharer you pin and your price floor allow, so a provider whose only allowed sharer is dear is still tried, and a provider whose every sharer you block or price out never takes a place.

x-aile-model on the answer names the provider that served, as <provider>/<model>, and the answer's model is the id you sent (auto/claude-sonnet-5). No provider listing the id is a 404, and none with a sharer online is a 503, which says so when it is your sharer lists or price floor that ruled every sharer out. The request's trace lists each provider tried as a target of a route with no name. The non-chat endpoints still take <provider>/<model>; auto/ there is a 400.

Keys made before auto/ may have Let a bare model id use any provider on, which does the same for a bare id with no prefix (optionally limited to a list of providers). It still works; a key's Routing shows it only while it is on, so it can be turned off, and new keys do not offer it.

The same levers, pinned to a key

Most of these can be attached to the key itself, for clients that cannot set custom headers, with a key's Routing button in Calling → API keys: provider, providers to leave out, a discount off list (the 80% form of max price), a max discount (the floor), a max cost per request, allowed and blocked sharers, speed first, moving failing sharers back, keeping a conversation on one sharer, and, under Advanced, one sharer handle or one machine. A key can also refuse self-hosted models: every road to one (local/, x-aile-provider: local, a route target) is then a 400. The discount, the floor, the cost cap and the sharer and provider lists bind the key's route targets too, the stricter of key and target winning.

The same button has Only providers that do not train on prompts, the key form of x-aile-data-collection: deny. It covers the whole key and its routes, so a route target cannot carry it, and an allow header cannot lift it. A request it cannot serve is a 400 before anything is held. Self-hosted models are refused, since the sharer's own machine reads the prompt, and so is any provider whose policy is depends on the account or not yet sourced: it fails closed. A key that saves a route to such a provider is refused with the reason.

Older keys may still carry a verified-only or fixed $/Mtok filter, which new keys no longer offer; those keep working and can be removed.

On the non-chat endpoints

Images, audio, video, music, embeddings, rerank, moderation, OCR and decisions honour the same headers and key pins, merged the same way. Two differences:

• the model must be <provider>/<model>; a bare id plus x-aile-provider is not accepted, auto/<model> is a 400 (any provider is chat only), and a header naming a different provider is a 400;
• x-aile-max-price and x-aile-min-price bind only the token-priced ones (embeddings and decisions). Everything else is priced per unit, and they are skipped there. The sharer and provider lists bind every endpoint.

These endpoints are served without a node, so x-aile-capacity: node finds no sharer and local is a 400. When nothing fits, the refusal names the check that emptied the pool. Each request is held against one chosen sharer, so a 402 there is final: a cheaper sharer is not tried.

The CLI shows the same view

1aile sharers --model gpt-5.2 --max-price 8 --verified

Every filter is applied by the server and echoed back; nothing is filtered locally, so the CLI, the API and the marketplace page never disagree about who is available.

Five flags map exactly onto five headers, which is the point: a choice you make browsing is one you can act on in a request.

The default listing order is the order requests route in, so the top row is the machine your next request goes to.

How the router chooses when you do not

Price is primary: cheapest first. Only among sharers quoting the exact same price does anything else matter: sharers whose account has passed a test of the model you asked for go first, then a health-weighted draw over probe result, cooldown, capacity headroom, and observed speed and success rate.

A cheaper sharer is tried first no matter how slow it is, unless you ask for speed first. If a dearer sharer is tried first (the one a conversation used before, say) and it is more than your balance or key limit allows, the router still tries a cheaper one before answering 402.

A sharer cooling down after failures is skipped until its cooldown ends. One that fails in ways the router does not penalise can stay cheapest, which is what the sharer lists, the price floor and moving failing sharers back are for. See Routing & failover for the full ordering and the two independent bounds on how long you wait.

Speed first

A key or a route can ask for its chat requests to go to the fastest sharer instead of the cheapest:

• on the key: tick Prefer speed over price on its Routing button ("prefer": "speed" in the key's filters);
• on a named route: Prefer set to Speed or Price ("prefer": "speed" or "price"). A route's own choice wins over the key's, so a route set to Price stays cheapest first on a key that prefers speed. Left on Follow key, it does what the key does.

Sharers are then ordered by how quickly they have recently started answering (their time to first token), in 500 ms bands, and price decides within a band. A sharer with fewer than three recent requests counts as middling until it has more, so a pool with no history orders by price as usual. Speed is measured per account across the models it serves, and forgotten when Aile restarts.

It is off unless you turn it on, applies to chat only (not the non-chat endpoints), and never to self-hosted models, which keep their own order. A sharer whose key its provider refused, and one that keeps failing a key that moves such sharers back, still go last. A request ordered this way is marked on its usage row.

Session affinity

1x-aile-session: <your-session-id>

Pins a conversation to the account that served it. That keeps the provider's prompt cache warm, and it keeps the model's earlier reasoning readable: Codex refuses reasoning produced on another account, and Anthropic silently drops Claude Sonnet 5.5 and Haiku 5.5 thinking produced on another account. The verdict comes back as x-aile-session-affinity: fresh, or what the pin resolved to. Pins are kept per API key, and a request that names a sharer, machine or account keeps its own.

You rarely need to send it. Aile also reads the id your client already sends:

A prompt_cache_key is read last, and it pins each conversation sent under it rather than everything that shares it: OpenAI defines it as a label for requests that share a prompt prefix, and an application may send one value for every user of a feature. Sharing a key therefore never pulls unrelated conversations onto one account, while each conversation still returns to its own.

A client that sends none of these still has its conversation recognised. When the first answer calls a tool, the next turn sends that call's id back and goes to the same account (answer pins, below). Otherwise the conversation is recognised from the second turn on, by its opening messages and first answer, and goes back to its account from the third turn. A one-off request whose answer calls no tool is never pinned.

One session often holds several conversations at once: Claude Code and the Codex CLI run subagents and background calls under the main conversation's session id. Each conversation keeps its own account (one that finished elsewhere no longer moves the others), and a new one starts where the session last was. Aile tells them apart by the client's own thread id where it sends one (Codex's thread-id, a Claude Code subagent's x-claude-code-agent-id), and otherwise by the conversation's system prompt and first message.

The answer a client sends back names its account too. Continuing a conversation, a client returns, byte for byte, what the previous answer held: the model's encrypted reasoning (a Claude thinking signature, a Responses encrypted_content, the encrypted reasoning in a chat answer) and its tool call ids. Aile keeps a digest of the latest answer's reasoning and of its first distinctive tool call id, and sends the next turn to the account that produced that answer. That is the closest match there is, so it decides first: the reasoning, then the tool call, then the thread, then the session. It holds when the client names no session, when two conversations open with the same prompt, and on Gemini, whose tool call ids Aile mints itself. x-aile-session-affinity can therefore read pinned on a request that sends no session id. A digest that two different accounts produced pins nothing. Only digests are kept, never the reasoning or the id.

A stream pins its account only once it has finished cleanly, and an account that fails the session (a cut stream, an error, a failover) loses the pin, so the next request is not sent back to it. So does an account a route's first-token limit dropped: a dropped attempt never pins.

When the account holding the conversation is a busy subscription account (a sharer's consumer plan, such as Claude Code or Codex, serves one request at a time, and is often finishing a background call or a subagent's turn), Aile waits up to 10 seconds for it before moving the turn to another sharer, because a move costs the whole prompt cache and any reasoning bound to that account. It waits only on a streamed request, or a buffered one the deployment holds open against the edge timeout, only when no other request is already queued for that account, and not under a route's first-token limit. A new subagent conversation never waits behind its parent's account, and every other busy sharer is waited on for 1 second.

A key can turn this off: untick Keep a conversation on one sharer on its Routing button (stored as "sticky": false in the key's filters). Each request is then priced and ordered afresh. The session id still reaches the provider, whose own cache may key on it; only Aile's pin stops.

Sharers that keep failing

Tick Move sharers that keep failing to the back on a key's Routing button ("demoteFailing": true) and a sharer that fails that key's requests 3 times within 5 minutes goes to the back of the order for the next 10 minutes. A request that succeeds through it clears the count. It is demoted, never removed: when it is the only sharer left, it still serves. To skip a sharer for good, block it instead.

Only the sharer's own failures count: a network failure, an empty answer, or a provider error or rate limit the router fails over on. Aile's own deadlines and network faults, a request you cancelled, an error your request caused, and a first-token limit running out do not. It is kept per key, per provider and per sharer, in memory, so a restart forgets it, and it never touches the sharer's standing with other callers.

Route order and first-token limits

A named route tries its targets in one of three orders, set per route:

Whatever the order, the next target is tried only when one fails, and the sharer order inside each target is unchanged: cheapest first, or fastest first where the route prefers speed. The route is stored as "order": "cheapest" or "round-robin"; in order is stored as nothing.

A route with two targets or more can also carry a first-token limit ("ttftMs", 1,000 to 60,000 ms; the dialog takes seconds). When a target has produced no output within it, across every sharer tried for that target, Aile drops it and moves to the next target. Nothing is charged for the dropped attempt, and the sharer is not marked down for it, though the conversation's pin leaves it.

• You receive nothing while a target is waiting, not even headers, for up to the limit. Set it above the time a healthy answer takes to start.
• The last target tried is never cut: it answers however slowly, as with no limit.
• It applies only to a streamed request on your balance. A request paid with x402, a request that is not streamed and a self-hosted target ignore it.

Each request's trace shows which target and sharer served it and what happened to the ones before: Account → API usage → Requests, or GET /keys/usage/requests while signed in.

Daily budgets

A named route, and each of its targets, can carry a daily budget in dollars ("budgetUsdPerDay"). It counts what the key is charged through that route from 00:00 UTC, and resets then.

• A route that has spent its budget is refused with a 402: "route <name> spent its $<budget> daily budget; resets 00:00 UTC". Nothing is held or sent.
• A target that has spent its own is skipped, and the route moves on to its next target. The trace shows it as budget spent. When every target has spent its budget, the answer is one 402 naming them all.

A budget is a soft cap. Requests already running when it is reached finish and are counted, so a busy route can go over by up to one charge per request in flight. The key's spend limit is soft in the same way; only your balance is a hard limit. A budget counts your share of each charge: nothing for a request a stake window paid, the discounted price under the stake-funded discount.

A target's spend is kept under what it calls (provider, model and any pinned sharer), so reordering a route keeps each figure, and editing a target starts it afresh. Spend is counted for every request through a named route, so a budget set mid-day starts from what the route has really spent today. Two targets that call the same thing would share one figure, so only one of them may carry a budget: saving a route where both do is refused.

Dry-run a route

Before you point a client at a route, you can see what a request would do, without sending it: Dry run on a saved route, or Dry run a request… on a key's Routing button. It is POST /keys/route-dry-run while signed in.

Give it a model or a route name, and optionally the endpoint, a request body and the headers you would send (provider, max price, price floor, cost cap, allowed or excluded sharers, excluded providers, session id). A model written auto/<model> (any provider) shows the providers it would try, in order, as targets. For each target, in the order it would be tried, it shows:

• a refusal before any sharer is asked, and why: a spent budget, an unpriced model, a price or cost cap no sharer fits, a body the cost cap cannot bound (the same 400 a real request gets, after which the next target is tried), a data-collection setting;
• the sharers each of your filters removed, by name (your sharer lists and price floor included), and how many sharers are unavailable right now or were passed over for their own reasons (cooling down, busy, no payout wallet, the model switched off). Those are counts, not names, as the market does not show them either;
• the sharers left, in order, with each one's quote for the request, whether it has passed a test of the model and how fast it has been, which one would be tried first and any tied with it. At most 50 are listed per target; the rest are counted;
• whether the stake-funded discount could apply.

It reads the key as saved, so save your edits first. It charges nothing, sends nothing to any sharer and writes nothing, and asking does not move a round-robin route's turn. It cannot know what a sharer will answer (a sharer that fails is passed over and the next tried), and it does not check your balance or the key's spend limit, which a real request checks at the real price. Nor can it see a provider adding a thinking budget on top of the output cap, which a cost-capped request finds out only once its request is built. Without a body it prices a one-line prompt; a body larger than 1 MiB as JSON is refused, so send the prompt and output cap, not the attachments.

A route across providers

To route one model across every provider that lists it, let Aile build the targets: Create a route across providers on a key's Model routes tab, or Route across providers on the model's /market page. GET /keys/route-template?model=<model>&key=<key id> is the same lookup. Each provider whose model has the same name, or the same once dots and underscores read as dashes, becomes a target, cheapest first, up to 10. A name that only starts the same (a dated or -thinking variant) is listed under ambiguous and never added, and self-hosted capacity is never added. With key, that key's provider pin, excluded providers, sharer lists and data-collection setting leave out what it would refuse, each named under skipped; its price ceiling and floor are not applied, since they bind per sharer when a request is served. The lookup writes nothing.

A saved route keeps its targets as you edit them. To have the providers chosen afresh on every request instead, send auto/<model> (any provider).

A header that no longer does anything

x-aile-region is not consulted. It was closed as a security hole: only the sharer's own server-derived country code routes egress, because a caller-supplied region is a request to be routed through somewhere, not a fact.