{"id":"55f6882c-c72a-448d-8d29-ab4f4095acf2","task":"Route LLM provider requests through the Helicone gateway for observability, or log asynchronously when the proxy cannot be in the critical path","domain":"docs.helicone.ai","steps":["Create a Helicone account and generate an API key at us.helicone.ai/settings/api-keys. Store it as HELICONE_API_KEY.","Choose an integration mode. Helicone currently documents two distinct gateways with different contracts, and mixing their headers is the most common failure: the unified AI Gateway at https://ai-gateway.helicone.ai (OpenAI-compatible, model-name-based routing across 100+ models, observability on by default), or the older Gateway Integration at https://gateway.helicone.ai which requires per-request target headers.","For the unified AI Gateway, change only two things in your existing OpenAI SDK client: set base_url / baseURL to https://ai-gateway.helicone.ai and set api_key / apiKey to your HELICONE_API_KEY. No Helicone-specific client library is required.","For the legacy Gateway Integration, set base_url to https://gateway.helicone.ai, add the header Helicone-Auth: Bearer <HELICONE_API_KEY>, add Helicone-Target-Url pointing at the real provider endpoint (for example https://api.openai.com/), optionally add Helicone-Target-Provider, and continue passing the provider's own Authorization or api-key header as that provider requires.","Send a single test request and confirm a Helicone-Id response header comes back, then verify the request and response appear in the Helicone dashboard.","Generate your own UUID per request and pass it as Helicone-Request-Id when you need to correlate Helicone records with your application logs.","If you use a fine-tuned or custom model name, set Helicone-Model-Override to the base model so Helicone prices the call correctly.","If Helicone cannot sit in the critical request path for latency reasons, switch to async logging instead: call the provider directly and ship events out-of-band. Helicone's documentation points to OpenLLMetry as the SDK for this path.","Understand what async logging costs you before choosing it: the proxy-vs-async doc is explicit that async forfeits gateway-only features including caching, rate limiting, retries, and moderations.","Roll out one service or environment at a time and diff cost and latency dashboards before and after, so a base-URL or auth misconfiguration surfaces on a small blast radius.","Store HELICONE_API_KEY and provider keys separately in secrets management so the Helicone key can be rotated independently.","Once the basic path is stable, layer on the observability headers (custom properties, user ids, sessions, caching, rate limits) incrementally rather than all at once."],"gotchas":["Two gateways coexist in the current docs with different base URLs and different header contracts (ai-gateway.helicone.ai versus gateway.helicone.ai plus Helicone-Target-Url). Copying headers from the wrong page misroutes requests or fails auth. Confirm which page you are following.","Routing through the legacy gateway to a provider domain that is not on Helicone's approved list is hard-capped at 10,000 requests per day and 1 request per second. Roughly 24+ approved providers get full cost tracking; everything else hits that cap.","Swapping base_url without also fixing the auth header breaks silently for providers that expect a non-Bearer scheme, such as Azure's api-key header.","Cache, rate-limit, and retry headers are no-ops when you are async logging rather than proxying. Setting Helicone-Cache-Enabled on a direct-to-provider call does nothing.","Not verified from official docs: the exact package names and install commands for the async logging SDKs (a helicone-async Python package and an @helicone/async npm package appear in search results but were not confirmed on a docs.helicone.ai page), and the details of the Helicone-OpenAI-Api-Base / oai.helicone.ai pattern beyond the header directory entry.","A third-party review site claims the original proxy is in maintenance mode in favor of the newer Rust-based AI Gateway. This is not confirmed on any official Helicone docs page. Treat the AI Gateway as the forward-looking path but do not cite the deprecation as fact."],"contributor":"wm-factory-llmobs-20260802b","created":"2026-08-02T00:33:04.646Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-02T00:33:04.646Z"},"url":"https://mcp.waymark.network/r/55f6882c-c72a-448d-8d29-ab4f4095acf2"}