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

# Changelog: October 2026

> What changed in Mesh in October 2026.

**October 2026**

The Analytics API documented, with a runtime `meta` endpoint and `end_user_id` as a new dimension and a new `tier` column in its exports; API version 2026-11 and a per-request charge receipt (coming to production); single sign-on with Okta; Gemini Live on realtime; Mesh Code desktop app; limit a BYOK key to models; fal image models on image edits; Gemini transcription diarization, word timestamps and language; clearer audio errors; fixed usage keys on all three inference endpoints; web search priced per engine; per-request provider pinning; pre-inference token counting; new chat and messages request fields; more usage filters

## The Analytics API is documented

**Added.** `GET /v1/analytics/*` now has a reference page:
[Analytics API](https://developers.meshapi.ai/docs/reference/analytics-api.md). It groups your traffic by any of
13 dimensions, two at a time, over any range, measuring any 12 of 31 measures —
the generic query behind the dashboard's Analytics screens, callable with an
`rsk_` key that holds `usage:read`.

**Added.** `GET /v1/analytics/meta` enumerates that surface at runtime: every
dimension and measure with its properties, each panel's pin filters, the caps and
the raw-window boundary, generated from the same definitions the query layer uses.
The answer is specific to the calling key — it reports which dimensions *you* may
group by — so a client that reads it at startup cannot drift from the API the way a
hard-coded list can.

**Added.** `end_user_id` — the `safety_identifier`, or the deprecated `user`, that
you send on a request — is now
one of those dimensions, so you can break spend, errors or latency down per end
user. It is kept per request rather than in the hourly rollup, so it reaches back
31 days rather than 24 months, and a range older than that is refused outright
instead of answered over the part that is covered.

The page covers what the responses say about themselves, which is the part that
is easy to misread: the `population` every answer echoes, the `coverage_pct` that
says how much of the traffic a latency figure could be computed over, the
`estimator` that names how a percentile was derived, and the `tier` that says
which store answered.

**Changed.** A team lead can now break their analytics down by member. Their
rows have always spanned the teams they lead, but `group_by=member_user_id` was
refused as though they could only see themselves; it is accepted, and with no
filters set it is also the axis an omitted `group_by` picks for them. An
ordinary member and an `rsk_` key are still fixed to one member and still
refused. The axis is not labelled, so the rows carry raw subject ids.

**Changed.** The CSV and Excel exports (`/v1/analytics/usage/summary.csv` and
`.xlsx`) carry a new `tier` column **at index 2**, between `retries` and `since`,
shifting every later column one place right. If you hold an analytics export
taken before 27 October — through the API or downloaded from the dashboard — and
something parses it by column position, read by header name instead.

## A full charge receipt on every request — API version `2026-11`

**Added.** Version `2026-11` is out (released 25 October) and you can pin it today. Under
it, `cost_breakdown.lines` on a usage row covers every kind of charge, not only
token-metered text:

```bash theme={null}
curl https://api.meshapi.ai/v1/usage/events \
  -H "Authorization: Bearer rsk_<key>" \
  -H "Content-Type: application/json" \
  -H "X-Mesh-Version: 2026-11" \
  -d '{"org_id": "<ORG_ID>", "limit": 20}'
```

Every line says what it was charged on and how: `quantity` and `unit` (`tokens`, `images`,
`megapixels`, `seconds`, `characters`, `utf8_bytes`, `calls` or `requests`), the `rate_usd`
that applied — `null` on a flat charge such as a BYOK `platform_fee` — the `amount_usd` it
produced, a `modifiers` list saying what the rate was qualified by (a resolution tier,
`long_context`, `flex`, `with_audio`, or how it was derived, such as `tier_fallback`), and
`charged`, which is `false` for a model cost you paid on your own provider key. The
breakdown itself gains `rounding_usd`; a token line keeps its `tokens` and
`rate_per_1m_usd`. So an image or video request will read as the seconds, resolution and
audio it was billed for, where today it carries no breakdown at all.

The endpoints are `POST /v1/usage/events`, `GET /v1/usage/requests/{request_id}` and
`GET /v1/usage/events/{event_id}/attempts` — see [Usage API](https://developers.meshapi.ai/docs/reference/usage-api.md).

**Changed.** Under `2026-11`, `CostLineOut.tokens` and `CostLineOut.rate_per_1m_usd` are
`null` on lines that are not billed by the token (images, video, flat fees); read
`quantity` with `unit`, and `rate_usd`, for those.

**The receipt is not switched on in production yet.** Pin `2026-11` now and nothing about
your usage rows changes until it is: no caller receives the receipt fields in the meantime,
whatever they pin. Pinning early costs nothing and saves a second change later.

**A receipt covers rows recorded after the switch.** A breakdown is written when the
request is billed and is never rebuilt on read, so paging back over older history under
`2026-11` returns what each row was recorded with: the token-only shape with the receipt
fields `null` where the charge was token-metered, and `cost_breakdown: null` where it was
not.

**A request that sends no `X-Mesh-Version` and has no key pin stays on `2026-08` and does
not get these fields.** There a row keeps the token-only breakdown with the figures it
carries today, and a charge that shape cannot express — an image, a video, or a text
request whose image input is priced at its own rate — reports `cost_breakdown: null`
rather than a partial breakdown. Nothing is removed from `2026-08`. Send the header, or
[pin it on your key](https://developers.meshapi.ai/docs/reference/api-versioning.md#pinning-a-whole-api-key), to use the
receipt.

## Responses will be converted back to the version you pinned

**Changed.** Converting a response back to the shape an older version promises is not yet
switched on in production. Until it is, a request that sends no `X-Mesh-Version` and has
no key pin — or that pins `2026-08` — receives two fields that belong to `2026-09`:
`pricing.discounted` on the models endpoints, and `request_id` on video task bodies.

When the conversion is switched on, those two fields stop reaching unpinned requests. That
is `2026-08` behaving as [API versioning](https://developers.meshapi.ai/docs/reference/api-versioning.md) describes it, and
neither field is being removed from the API — both stay in `2026-09` and `2026-11`. **If
your code reads `pricing.discounted` or a video `request_id`, pin `2026-09` or `2026-11`
before this lands.** Pinning is also what stops the same surprise at the next boundary.

## Pin a request to one provider

**Added.** An optional `provider` field pins a single request to one upstream provider:
that provider serves the request or it is refused, and the request is never rerouted. It
is accepted in the body of `POST /v1/chat/completions`, `/v1/responses`, `/v1/messages`,
`/v1/images/generations`, `/v1/video/generations`, `/v1/batches`, `/v1/chat/compare` and
`/v1/audio/speech`, and as a multipart form field on `/v1/audio/transcriptions`,
`/v1/audio/translations` and `/v1/audio/transcriptions/translate`.

```bash theme={null}
curl https://api.meshapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $MESH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id-from-GET-/v1/models>",
    "provider": "<provider-slug>",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

A request can repeat the provider its API key is pinned to, but cannot replace it. An
unusable pin returns `400 invalid_provider_pin` with `details.reason` of
`invalid_provider`, `conflicts_key_pin` or `disabled`; a pin the model cannot be served on
returns `model_not_available_on_pinned_provider`, where `details.pin_source` (`key`,
`request` or `both`) says which setting to change. When per-request pinning is turned off, a
request that includes `provider` is refused rather than ignored. `/v1/messages` returns pin
refusals in the Anthropic error envelope, which has no `details` object; on
`/v1/chat/compare` a pin that cannot serve one model surfaces as that model's `error_code`
inside the 200 response while the others are still compared, and an invalid pin returns a
top-level 400 before any model runs; on `/v1/video/generations` the pin applies only to the
submit step. `/v1/embeddings` is unchanged — its `provider` field
stays a soft preference and does not pin.

## Count input tokens before you send

**Added.** `POST /v1/messages/count_tokens` counts input tokens for an Anthropic-format
Messages body and `POST /v1/responses/input_tokens` for a Responses-format body, neither
running inference nor billing. `max_tokens` is optional on `count_tokens`, and the
`X-Mesh-Token-Count-Source` response header says whether a count is exact or an estimate.
Count requests follow model-access rules and per-key RPM and RPD limits, but not TPM limits
or spend caps.

## New request fields on chat completions and messages

**Added.** `POST /v1/chat/completions` accepts `max_completion_tokens` (at least 1); when it
and `max_tokens` are both sent, `max_completion_tokens` wins. `POST /v1/messages` accepts
`container`, `mcp_servers` and `service_tier`, and when Claude on Bedrock serves a
`/v1/messages` request the response carries Bedrock's native body, including `service_tier`,
`stop_details` and `container`.

## More usage filters

**Added.** Usage queries can be filtered by `provider`, `fault_owner`, `is_byok`,
`is_retry_attempt`, `stream` and `traffic_type` on `UsageFilter`, across the events list,
its count, the summary and the CSV export. With `is_retry_attempt` omitted, only the served
attempt is returned, as before.

## Single sign-on with Okta

**Added.** Enterprise organizations can let their team sign in to the Dashboard with
their company's Okta. An owner or admin connects an Okta OIDC app under
**Settings → Single sign-on** and verifies the email domain with a DNS record.
See [Single Sign-On (Okta)](https://developers.meshapi.ai/docs/getting-started/single-sign-on.md).

## Gemini Live on realtime audio

**Added.** `gemini-3.8-live` is available for bidirectional speech-to-speech on
`wss://api.meshapi.ai/v1/realtime`. Mesh translates between the OpenAI Realtime
event shape and Google's Gemini Live protocol, so an existing realtime client
works by switching the `model` query parameter — no code change.
See [Realtime Audio](https://developers.meshapi.ai/docs/capabilities/realtime-audio.md#supported-models).

## Web search is priced per engine

**Changed.** `POST /v1/web/search` is billed at the price of the engine that answered,
instead of a flat \$0.005: `native` \$0.005, `tavily` \$0.008 (\$0.016 with
`search_depth: "advanced"`), `tinyfish` \$0.005 plus \$0.001 per returned result
carrying `page_content`. Failed and empty searches are still free.
See [Web Search billing](https://developers.meshapi.ai/docs/capabilities/web-search.md#billing).

## Fixed `usage` keys on Responses and Messages; provider keys return on chat

**Changed.** `POST /v1/responses` and `POST /v1/messages` now return a fixed set of
`usage` keys whichever provider serves the request, all present and `0` when unused:

* **Responses:** `input_tokens_details` (`cached_tokens`, `cache_write_tokens`,
  `cache_write_1h_tokens`, `audio_tokens`), `output_tokens_details.reasoning_tokens`,
  `total_tokens`, `byok_used` and `fallback_triggered`.
* **Messages:** `cache_creation_input_tokens`, `cache_read_input_tokens`,
  `cache_creation` split by TTL, `byok_used` and `fallback_triggered`, on the response
  body and on `message_delta`. They were previously returned only when non-zero.

On all three endpoints, keys a provider adds on its own (such as `is_byok`,
`prompt_cache_hit_tokens` or `num_sources_used`) are returned alongside the fixed keys.
On chat completions they had been removed since the change below. This applies to every
API version. See [Usage Object](https://developers.meshapi.ai/docs/reference/usage-object.md).

## One `usage` shape on chat completions

**Changed.** `usage` on `POST /v1/chat/completions` (including the final chunk of a stream)
now has the same keys whichever provider serves the request, all present and `0` when
unused: `prompt_tokens_details` (`cached_tokens`, `cache_write_tokens`,
`cache_write_1h_tokens`, `audio_tokens`), `completion_tokens_details`, `byok_used` and
`fallback_triggered`. `total_tokens` is always `prompt_tokens + completion_tokens`. Keys a
provider added on its own, such as `is_byok` or `prompt_cache_hit_tokens`, are no longer
returned; a provider's cache hits appear as `cached_tokens`. This applies to every API
version. See [Reading the result](https://developers.meshapi.ai/docs/capabilities/caching.md#reading-the-result).

**Deprecated.** The top-level `usage.cache_creation_input_tokens` on Claude responses
duplicates `prompt_tokens_details.cache_write_tokens`. It is still returned; retirement
date to be announced.

## Limit a BYOK key to specific models

A provider key you register with Mesh used to serve every model Mesh routes to that
provider. **Allowed models** on the key (`allowed_models` in the API) now limits it to
exact model IDs or brand wildcards such as `openai/*`. A model outside the list is served
on Mesh's credentials and billed to your balance, or, with fallback off, refused with
`403 byok_model_not_allowed`. See
[Limit a key to specific models](https://developers.meshapi.ai/docs/capabilities/byok.md#limit-a-key-to-specific-models).

## Mesh Code

Mesh Code is a desktop app for agentic coding, with every Mesh model behind one key. It
plans, writes files, runs commands and starts dev servers inside a project folder you
choose; each step is either auto-approved by a mode you pick or shown to you as a diff
first. Version 0.2.4 (1 October) ships for macOS (Apple silicon), Linux (AppImage) and
Windows (x64). Download it from [GitHub](https://github.com/aifiesta/mesh-code).

## fal image models on `/v1/images/edits`

`fal-ai/gemini-3-pro-image-preview/edit` and `fal-ai/nano-banana-pro/edit` serve
`POST /v1/images/edits`, with one source image or several. They bill at the model's
per-image or per-megapixel rate. See
[Edit an image](https://developers.meshapi.ai/docs/capabilities/image-generation.md#edit-an-image).

## Gemini transcription: diarization, word timestamps and language

**Added.** `google/gemini-3.5-transcribe` now supports speaker diarization (`diarize`),
per-word timestamps (`timestamp_granularities[]` / `timestamps_granularity=word`), and a
language hint (`language` / `language_code`). Request `verbose_json` or `diarized_json` to
receive the `words` array with per-speaker `speaker_id`. `num_speakers` and
`diarization_threshold` are ignored — Gemini has no speaker-count control. See
[Speech to Text](https://developers.meshapi.ai/docs/capabilities/speech-to-text.md#available-models).

## Clearer audio errors

* Gemini speech-to-text accepts `.m4a`, `.mp4`, `.webm` and `.opus` audio, and a file a model
  cannot take is refused with a message that says why, not a generic capability error.
* A rate-limited ElevenLabs speech-to-text request moves on to fallback instead of
  failing as `422` `model_id: Field required`.

## Fixes

* A `tool` message whose `content` is a list of parts reaches Vertex Gemini models as
  its text instead of failing with `500`.
* A multipart upload sent to a JSON endpoint is a `422` validation error, not a `500`.
* Large usage exports no longer fail partway through.


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