Skip to main content
AddedAPIImagesAudioChangedDeprecated
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. 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:
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.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, 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 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.
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).

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.

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.

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.

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.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.

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.

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.

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.

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.