---
title: "OpenRouter best practices"
answer: "OpenRouter model IDs are routing aliases in `provider/model` form, not provider-native names. Coolhand records the alias you sent, so a change to the upstream provider behind that alias is invisible in your logs. Pin the alias you intend to compare over time before relying on its cost trend."
category: "Provider guides"
tags: ["openrouter","providers"]
published: 2026-08-30T13:57:52Z
updated: 2026-08-30T13:57:52Z
canonical_url: https://coolhandlabs.com/help/openrouter-best-practices
index_url: https://coolhandlabs.com/help.md
---

# OpenRouter best practices

OpenRouter model IDs are routing aliases in `provider/model` form, not provider-native names. Coolhand records the alias you sent, so a change to the upstream provider behind that alias is invisible in your logs. Pin the alias you intend to compare over time before relying on its cost trend.

---

## Model IDs use `provider/model` routing format

OpenRouter model identifiers are routing aliases, not provider-native names:

```
anthropic/claude-3-5-sonnet
openai/gpt-4o
google/gemini-2.5-pro-preview
meta-llama/llama-3.1-70b-instruct
```

The Model field in Coolhand shows the OpenRouter ID. When using `openrouter/auto` or similar auto-routing aliases, the logged model reflects the alias, not the model actually selected.

---

## Fallback routing can silently change the model

OpenRouter automatically falls back to another provider when one is rate-limited or unavailable. If you see unexpected model IDs in logs, fallback routing is the likely cause. OpenRouter does not guarantee the model you specified was the one used.

---

## Structured outputs

OpenRouter defines its own unified `response_format` that it enforces independently — it is not a simple passthrough. Supported types are `json_object` and `json_schema`. OpenRouter validates the request against its own schema and returns an error if the target model doesn't support the requested format. A **Response Healing** plugin is also available, which attempts to repair malformed JSON before returning it to the caller.

Docs: https://openrouter.ai/docs/guides/features/structured-outputs

---

## Caching

Coolhand captures **Cached Input Tokens** when the target provider reports a cache hit. **Cache Creation Tokens are never surfaced** for OpenRouter logs — even when routing to a provider (like Anthropic) that reports cache creation separately.

Cache TTL and invalidation depend entirely on the target provider. OpenRouter does not expose cache lifecycle details.

---

## Batch processing

OpenRouter has no native batch API. If you need batch processing for a specific provider, call that provider directly:
- OpenAI models → [OpenAI Best Practices](https://coolhandlabs.com/help/openai-api-best-practices.md)
- Anthropic models → [Anthropic Best Practices](https://coolhandlabs.com/help/anthropic-api-best-practices.md)
- Google models on Vertex → [Google Vertex AI Best Practices](https://coolhandlabs.com/help/google-vertex-ai-best-practices.md)

---

## Latency

Coolhand inherits OpenAI's latency logic for OpenRouter: it checks for an `openai-processing-ms` response header first, then falls back to the collector-provided `duration_ms`. Whether OpenRouter forwards that header is not documented — in practice, the fallback `duration_ms` (wall-clock including routing overhead) is the value most often captured. Not directly comparable to direct-provider latency figures.


---

Related:
- [Azure OpenAI best practices](https://coolhandlabs.com/help/azure-openai-best-practices.md)
- [AWS Bedrock best practices](https://coolhandlabs.com/help/aws-bedrock-best-practices.md)
- [Ollama best practices](https://coolhandlabs.com/help/ollama-best-practices.md)
- [Google Gemini best practices](https://coolhandlabs.com/help/google-gemini-best-practices.md)

[← All help articles](https://coolhandlabs.com/help.md) · [Provider guides](https://coolhandlabs.com/help/category/providers.md)