Usage & Requests
Usage summary
Authorization: Bearer lattice_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxdays is optional, an integer from 1 to 365, defaulting to 30. Out of range → 400 invalid_request.
type ProviderAdapter = {
id: ProviderId;
createChatCompletion(
request: ChatCompletionRequest,
ctx: ProviderRequestContext,
): Promise<ChatCompletionResponse>;
streamChatCompletion(
request: ChatCompletionRequest,
ctx: ProviderRequestContext,
): AsyncGenerator<ChatCompletionChunk, void, void>;
};
type ProviderRequestContext = {
apiKey?: string;
providerModel: string;
signal: AbortSignal;
}; One row per day in the lookback window. The top-level /usage endpoint aggregates across every application; the per-application variant scopes to one. estimatedCostUsd sums per-request cost estimates — days with requests against models that have no configured pricing will under-report cost for that slice.
Request log
{
"id": "chatcmpl-...",
"object": "chat.completion",
"created": 1755878400,
"model": "gpt-4o",
"choices": [
{
"index": 0,
"message": { "role": "assistant", "content": "..." },
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 42,
"completion_tokens": 118,
"total_tokens": 160
}
}| Query param | Type | Default | Notes |
|---|---|---|---|
applicationId | string | — | Filter to one application. |
model | string | — | Filter to one requested model name. |
provider | string | — | Filter to one provider id. |
status | 'success' | 'error' | — | Invalid value → 400 invalid_request. |
since | ISO date string | — | Invalid date → 400 invalid_request. |
until | ISO date string | — | Invalid date → 400 invalid_request. |
limit | integer, 1–200 | 50 | Out of range → 400 invalid_request. |
offset | integer, >= 0 | 0 | Negative → 400 invalid_request. |
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1755878400,"model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1755878400,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"Sure"},"finish_reason":null}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1755878400,"model":"gpt-4o","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":42,"completion_tokens":118,"total_tokens":160}}
data: [DONE]provider is null when a request failed before routing resolved one (e.g. an unknown model, or a quota/rate-limit rejection) — there's nothing to attribute the failure to yet. errorCode mirrors the LatticeErrorCode the client would have received.
Paging through results
type ChatCompletionChunk = {
id: string;
object: 'chat.completion.chunk';
created: number;
model: string;
choices: [
{
index: number;
delta: { role?: 'assistant'; content?: string };
finish_reason: 'stop' | 'length' | 'content_filter' | null;
},
];
usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number } | null;
};limit/offset are echoed back in the response so a client can compute whether it's reached the end (data.length < limit) without a separate total-count field.