Meta Endpoint

The /meta endpoint is the fallback mechanism for retrieving per-request FinOps metadata (cost, provider, credits) when the final streaming SSE frame is missing or when you need to look up cost data after a non-streaming request has completed.

Endpoint

GET /gateway/v1/meta/:requestId

The requestId is the value returned in the Cova-Id response header (or the requestId field of the streaming cova frame). It must be a valid UUID v4.

Authentication

Required. Provide your CoreValue API key as a Bearer token:

Authorization: Bearer $COVA_API_KEY

Path Parameter Validation

The requestId must match the UUID v4 pattern:

/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i

A malformed requestId returns 400 Bad Request.

orgId-Scoped Storage

Metadata is stored in Redis under an orgId-scoped key: {orgId}:{requestId}. A separate global existence marker is stored at exists:{requestId}.

Response Codes

Metadata is stored for 300 seconds (5 minutes) after the request completes. After the TTL expires, lookups return 202.

When to Use It

Example

cURL

curl https://gateway.corevalue.dev/gateway/v1/meta/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $COVA_API_KEY"

SDK

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

const res = await fetch(
  "https://gateway.corevalue.dev/gateway/v1/meta/550e8400-e29b-41d4-a716-446655440000",
  { headers: { Authorization: `Bearer ${process.env.COVA_API_KEY}` } },
);

const meta = parseGatewayMeta(res.headers);

if (meta) {
  console.log(meta.requestCost);  // actual cost in USD
  console.log(meta.provider);     // provider that served the request
  console.log(meta.model);        // model that served the request
}

from cova_gateway import fetch_meta

meta = fetch_meta(
    "550e8400-e29b-41d4-a716-446655440000",
    api_key=os.environ["COVA_API_KEY"],
)

if meta:
    print(meta.request_cost)
    print(meta.provider)
    print(meta.model)

200 Response Body

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "provider": "groq",
  "model": "groq/llama-3.1-70b-versatile",
  "status": "success",
  "requestCost": 0.0015,
  "estimatedCost": 0.023,
  "creditsRemaining": 48.77,
  "gatewayMode": "passthrough"
}

202 Response Body

{ "status": "pending" }

CovaGatewayMeta Fields

Related