LiteLLM + Meridian gateway ingest

Status: Beta · 2026-09-22
Egress: api.onaro.io:443 (HTTPS)

Meridian accepts LiteLLM generic_api callback payloads, maps them to OASA 0.2.0, and attributes usage to agents and chargeback dimensions. You operate LiteLLM; Onaro does not host your proxy.

---

Prerequisites

• LiteLLM proxy with generic_api logging enabled (LiteLLM generic_api docs)
• A Meridian ingest integration key with meridian:ingest scope (Bearer token)
• Outbound HTTPS from the LiteLLM host to https://api.onaro.io
• Optional: forward proxy if your network requires it (see below)

---

Ingest endpoint

POST https://api.onaro.io/v1/meridian/ingest/gateways/litellm
Authorization: Bearer MERIDIAN_INGEST_KEY
Content-Type: application/json

Replace MERIDIAN_INGEST_KEY with the key value shown once when you create the integration key in Meridian.

---

config.yaml template

Save as config.yaml on your LiteLLM host. Use placeholders only — substitute at deploy time.

general_settings:
  master_key: sk-litellm-local-master

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
    metadata:
      agent_id: finance-copilot
      cost_center: CC-4100
      pool_id: gpu-pool-a
      endpoint_id: cluster-east-1
      hosting: self_hosted

litellm_settings:
  success_callback:
    - generic_api
  generic_api_settings:
    api_base: MERIDIAN_INGEST_URL
    headers:
      Authorization: Bearer MERIDIAN_INGEST_KEY
    stream_options:
      include_usage: true

Set:

For Nutanix-style private clusters with pool/endpoint metadata, see companion file LiteLLM_Meridian_Nutanix.yaml in this guide folder.

---

Identity: declared vs registry

Meridian supports two attribution modes (often used together):

Declared mode (metadata on the model)

Set on each model_list entry under metadata:

• agent_id — Meridian agent external id
• cost_center — chargeback cost center
• pool_id — private GPU / capacity pool id
• endpoint_id — cluster endpoint id
• hosting — e.g. self_hosted, vendor_hosted

These fields flow from LiteLLM StandardLoggingPayload metadata.* into OASA.

Registry mode (virtual keys)

When callers use LiteLLM virtual keys, map user_api_key_hash (or equivalent key ref) to agents in Meridian:

1. Open Meridian → Settings → Gateway key registry
2. Add rows for gateway=litellm and each gateway_key_ref
3. Or upload CSV: gateway,gateway_key_ref,agent_id,cost_center,pool_id,endpoint_id

Unmapped keys appear in the Unmapped list after traffic arrives; map them inline from that UI.

---

Forward proxy

If LiteLLM must egress via a corporate proxy:

• Configure proxy env vars on the LiteLLM process (HTTPS_PROXY / HTTP_PROXY) so generic_api POSTs reach api.onaro.io:443
• Allowlist api.onaro.io on the proxy and any TLS inspection appliance
• Keep Authorization: Bearer MERIDIAN_INGEST_KEY out of logs and APM redaction rules

---

Verification

1. Send one chat completion through the proxy with metadata populated.
2. Confirm HTTP 200 from the ingest path (LiteLLM success callback logs).
3. In Meridian, check agent usage / ledger within the normal rollup window.
4. If attribution is missing, open Gateway key registry → Unmapped and map the observed key ref.

---

Related docs

• Internal payload notes: docs/INGEST-3-gateway-payloads.md (repo)
• Mapping schema: docs/gateway-mapping-schema.md (repo)