Sticky conversations

Route multi-turn conversations back to the same provider and reuse the warm KV-cache.
Multi-turn conversations get routed to the same provider via a buyer-supplied opaque tag on the X-Malibu-Conversation header. When the sticky provider serves turn N+1, its warm KV-cache is reused for the shared prefix and the request is billed at a discounted rate for the cached tokens.

How it works

  • The tag is opaque and buyer-chosen. Use a stable per-thread identifier — a UUID, a thread ID from your app, whatever’s convenient.
  • The gateway HMACs the tag with your account_id before forwarding, so one buyer’s thread-42 never collides with another buyer’s thread-42.
  • If the sticky provider is unavailable (disconnected, thermally throttled, admission-full), the request falls through to normal routing and cached_prompt_tokens will be 0.
  • Legacy providers that don’t report cache hits emit cached_prompt_tokens: 0 — safe to consume unconditionally.

Billing

Cached tokens are metered separately from fresh prompt tokens. See API → Usage object for the cached_prompt_tokens field and Network overview → Metering & billing for the prefix-cache formula.

Composition

X-Malibu-Conversation and X-Malibu-Pin-Provider compose: pinning trumps sticky. If you pin, sticky becomes redundant — the request will always go to the pinned Mac (or fail).

When to use sticky

  • Chat UIs. One conversation_id per thread — repeated system prompts and message history get cached.
  • Agent loops. Same reasoning trace across many tool-call turns — massive prefix reuse.
  • Long-context RAG. Retrieved documents in the system prompt stay warm across follow-ups.
Not useful when every request has a fresh prompt with no shared prefix.