Extract per-call cost, usage, and provider metadata from gateway responses via CovaGatewayMeta.

Per-Call FinOps Metadata

CoreValue Gateway returns per-call cost and wallet metadata in every response. This is the competitive differentiator — no other AI gateway surfaces this in the response path.

Tier: Available on all tiers. creditsRemaining is only set for pay-the-blanket (PTB) requests, not BYOK.

Where Metadata Lives

Non-Streaming

Metadata is in Cova-* response headers. Use wrap() to parse into typed CovaGatewayMeta:

import { wrap } from "@cova/gateway";

const covaResponse = wrap(response, response.headers);
console.log(covaResponse.gateway.requestCost);
console.log(covaResponse.gateway.creditsRemaining);

Streaming

The gateway appends a final SSE event after data: [DONE]:

data: {"cova":{"requestId":"...","provider":"openai","model":"gpt-4o","status":"success","requestCost":0.0015,"creditsRemaining":48.77}}

Use streamChat() to get this as a final yielded value. See streamChat.

Fallback: /meta Endpoint

If you need metadata after the response is gone (e.g., async processing):

curl https://gateway.corevalue.dev/gateway/v1/meta/<requestId> \
  -H "Authorization: Bearer sk-cova-..."

200 — metadata available (returns CovaGatewayMeta JSON)
202 — request still in flight or expired (5-minute TTL)
404 — requestId belongs to a different org
400 — malformed UUID

Fields

Field	When Set	Use Case
`requestCost`	After completion (non-stream) or final SSE (stream)	Display actual cost to user
`estimatedCost`	Upfront on all PTB responses	Show "estimated cost" before completion
`creditsRemaining`	After settlement (PTB only)	Warn user when balance is low
`provider`	All responses	Show which provider served
`model`	All responses	Show which model was used
`gatewayMode`	When translation enabled	Detect if request was translated
`translationWarning`	When fields dropped in translation	Warn user about dropped fields

Use Case: Display Cost to End User

const covaResponse = wrap(response, response.headers);
if (covaResponse.gateway.requestCost) {
  console.log(`This call cost $${covaResponse.gateway.requestCost.toFixed(4)}`);
}
if (covaResponse.gateway.creditsRemaining !== undefined && covaResponse.gateway.creditsRemaining < 5.0) {
  console.warn("Low balance: $", covaResponse.gateway.creditsRemaining.toFixed(2));
}

Use Case: Async Cost Tracking

const metaResponse = await fetch(
  `https://gateway.corevalue.dev/gateway/v1/meta/${covaResponse.gateway.requestId}`,
  { headers: { "Authorization": "Bearer sk-cova-..." } }
);
if (metaResponse.status === 200) {
  const meta = await metaResponse.json();
  console.log(meta.requestCost);
}

Per-Call FinOps Metadata

On this page