Service Tiers

service_tier is an optional field on POST /v1/chat/completions and POST /v1/responses. It selects the capacity pool the provider serves your request from.

Value	What it does
`"auto"`	Inert. Forwarded unchanged — no change in price, latency or behaviour.
`"default"`	Inert. Same as `"auto"`.
`"flex"`	Serves the request from OpenAI’s discounted, slower capacity pool and bills it at OpenAI’s flex rates.

Omitting the field is the same as sending "default".

Those three are the only accepted values. "priority", "fast" and "scale" are OpenAI’s more expensive tiers and are not supported — they are rejected with 422 before the request reaches a provider:

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "details": [
      {
        "type": "literal_error",
        "loc": ["body", "service_tier"],
        "msg": "Input should be 'auto', 'default' or 'flex'",
        "input": "priority",
        "ctx": { "expected": "'auto', 'default' or 'flex'" }
      }
    ]
  },
  "request_id": "req_01JQ..."
}

Which models serve flex

Flex is an OpenAI feature. It is refused on every other provider, whatever model you name. Within OpenAI, only the models OpenAI publishes a complete flex rate card for can serve it. That set changes as OpenAI’s pricing moves, so read it from GET /v1/models rather than hardcoding a list:

pricing.flex_input_usd_per_1m — this is the signal to branch on. A flex rate is published only for a model whose provider can actually serve the tier, so its presence is the closest thing to a yes.
supports_flex — the model’s own declaration, and weaker than it looks. It does not account for which upstream serves the model, so a row reached through a provider with no flex tier still reports true.

curl -s https://api.meshapi.ai/v1/models \
  -H "Authorization: Bearer <YOUR_RSK_KEY>" \
  | jq -r '.[] | select(.pricing.flex_input_usd_per_1m != null) | .id'

Neither field is a guarantee, for two reasons. GET /v1/models publishes a model’s default pricing row, while the tier is checked against the row for the provider your request actually resolves to — so a key with its own provider credential, a key pinned to a fixed_provider, or a brand routing rule can land on a row with no flex tier. And a model can acquire a rate that flex does not price after its flex prices were published. Treat a published flex rate as “expected to work” and handle the 400 below.

What it costs

Flex tokens bill at OpenAI’s published flex rates, materially below the standard rates. The rates are transcribed from OpenAI’s card per model rather than derived from a discount, so there is no ratio to apply — the per-model pricing.flex_* values in GET /v1/models are the contract. Prompt caching still applies on a flex request and bills at the model’s flex cache rates. A flex request is never billed at a standard rate: if any rate the model carries has no flex counterpart, the request is refused rather than priced off the standard card. Flex is not the same product as the Batch API, which is asynchronous and priced off its own rate card.

Sending a flex request

curl https://api.meshapi.ai/v1/chat/completions \
  -H "Authorization: Bearer <YOUR_RSK_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-mini",
    "messages": [{ "role": "user", "content": "Summarise this changelog." }],
    "service_tier": "flex"
  }'

The same field works identically on POST /v1/responses.

A model that cannot serve flex is refused

A flex request for a model that cannot serve the tier is rejected with 400 model_capability_not_supported before anything is sent upstream. It is never silently downgraded to the standard tier and billed at the standard price. Two messages, two causes. The provider your request resolved to has no flex tier, or the model publishes no flex input/output rate for the context length it would use:

{
  "error": {
    "code": "model_capability_not_supported",
    "message": "Model 'openai/gpt-4o-mini' is not available on the 'flex' service tier from the provider resolved for this request. Omit service_tier, or use a model that publishes flex pricing."
  },
  "request_id": "req_01JQ..."
}

Or the headline rates are there but something else on the card is not — a cache, reasoning or audio rate the model charges that flex publishes no counterpart for. This one can appear on a model that served flex yesterday, so handle it rather than treating a published flex rate as permanent:

{
  "error": {
    "code": "model_capability_not_supported",
    "message": "Model 'openai/gpt-5-mini' is not priced for the flex service tier. Retry without `service_tier`."
  },
  "request_id": "req_01JQ..."
}

Both remedies are the same: drop service_tier, or pick a model that publishes a flex rate.

Knowing which tier actually served

A request can end up on the standard tier even though you asked for flex. If retry and fallback moves the request to a different provider or model that cannot serve flex, the tier is dropped for that attempt and the request is served at the standard tier — and billed at that target’s standard rate, not at the flex rate you asked for. Two ways to see what happened:

Surface	When to use it
`X-Mesh-Service-Tier` response header	Non-streaming responses. Present only when flex served; absent means standard.
The request’s usage record	Streaming responses, where the headers are already sent before the attempt finishes, so there is no header to read. `service_tier` on the record is the authority.

Caching is per tier

The gateway response cache keys on the service tier, so a flex request never replays a response that was served at the standard tier, and vice versa. Two otherwise-identical requests on different tiers are two cache entries.

Flex is slower by design

That is the trade you are making. Raise your client’s timeout before you use it — OpenAI recommends allowing up to 15 minutes for a flex request.

The per-request timeout field is capped at 600 seconds, on every tier. A flex request that needs longer than that fails with 504 gateway_timeout, which is expected under load — retry it, or send the request without service_tier.

When OpenAI’s flex capacity is full

Flex runs on spare capacity, so it can be unavailable when the standard tier is fine. OpenAI does not charge for a request refused this way, and neither do we:

{
  "error": {
    "code": "upstream_error",
    "message": "Service tier is at capacity. Please try again later.",
    "provider_code": "provider_overloaded",
    "provider_error": {
      "provider": "openai",
      "status": 429,
      "message": "Service tier is at capacity. Please try again later."
    }
  },
  "request_id": "req_01JQ..."
}

It is served as 503 with a Retry-After header. Mesh treats it as a capacity condition rather than a rate limit, so the request is retryable and eligible for fallback to another model. Two remedies:

Retry with exponential backoff, honouring Retry-After.
Retry without service_tier (or with "auto") to take standard capacity at the standard price.

See the Error Reference for the full error contract.

Where flex is not available

These are deliberate, not gaps:

Surface	Why
`/v1/batches`	Batch is already a discounted asynchronous product with its own rate card. A `service_tier` on a batch line is not read by Mesh — it is neither validated nor priced, so it buys you nothing.
Video generation	Video requests have a `service_tier` field of their own. It is an unrelated BytePlus parameter and has nothing to do with OpenAI’s tiers.
`"background": true` on `/v1/responses`	A background job settles outside the request, where the flex rate card cannot be applied. Combining the two is refused with `400`.
Realtime WebSocket endpoints	No tier selection.

The background refusal looks like this:

{
  "error": {
    "code": "model_capability_not_supported",
    "message": "background=true cannot be served on the 'flex' service tier. Omit service_tier, or run the request without background."
  },
  "request_id": "req_01JQ..."
}

Tracking flex spend

service_tier is recorded on every usage record and is filterable in usage analytics, so flex spend can be separated from standard spend without tagging requests yourself. See the Usage API.

Introduction

Accounts & Access

Core Inference

Retrieval & Search

Multimodal

Operations

Mesh CLI

Platform

Reference

Which models serve flex

What it costs

Sending a flex request

A model that cannot serve flex is refused

Knowing which tier actually served

Caching is per tier

Flex is slower by design

When OpenAI’s flex capacity is full

Where flex is not available

Tracking flex spend

​Which models serve flex

​What it costs

​Sending a flex request

​A model that cannot serve flex is refused

​Knowing which tier actually served

​Caching is per tier

​Flex is slower by design

​When OpenAI’s flex capacity is full

​Where flex is not available

​Tracking flex spend

Which models serve flex

What it costs

Sending a flex request

A model that cannot serve flex is refused

Knowing which tier actually served

Caching is per tier

Flex is slower by design

When OpenAI’s flex capacity is full

Where flex is not available

Tracking flex spend