AI Gateway Generation Lookup and Usage API
AI Gateway records every generation it serves. Look up a generation by ID to inspect its provider, latency, token usage, cost, and finish reason. You can also check your team's credit balance and lifetime spend.
Open the AI Gateway tab in your Vercel dashboard. The top of the page shows your current AI Gateway Credits balance and recent spend; the Generations view shows individual requests with cost, latency, and token usage.
Use the REST API to look up individual generations or monitor your balance:
GET /v1/generationreturns cost, latency, finish reason, and token usage for a specific generation.GET /v1/creditsreturns the team's remaining credit balance and lifetime spend.
For aggregated spend across a date range (grouped by user, model, tag, provider, and more), see Custom Reporting.
Install AI SDK 7 and set AI_GATEWAY_API_KEY before running this script. It tags a request, captures its generation ID, waits for usage ingestion, and prints the available provider, latency, token, and routing fields:
import { gateway, generateText } from 'ai';
const result = await generateText({
model: 'anthropic/claude-sonnet-5',
prompt: 'Explain quantum computing in two sentences.',
providerOptions: {
gateway: {
tags: ['feature:chat'],
},
},
});
const gatewayMetadata = result.providerMetadata?.gateway as
| { generationId?: string; routing?: unknown }
| undefined;
const generationId = gatewayMetadata?.generationId;
if (typeof generationId !== 'string') {
throw new Error('Missing generation ID');
}
async function getGeneration() {
for (let attempt = 0; attempt < 10; attempt++) {
try {
return await gateway.getGenerationInfo({ id: generationId });
} catch (error) {
const statusCode =
typeof error === 'object' &&
error !== null &&
'statusCode' in error &&
typeof error.statusCode === 'number'
? error.statusCode
: undefined;
if (statusCode !== 404 || attempt === 9) throw error;
await new Promise((resolve) => setTimeout(resolve, 2000));
}
}
throw new Error('Generation lookup failed');
}
const generation = await getGeneration();
console.log(
JSON.stringify(
{
generationId,
provider: generation.providerName,
model: generation.model,
timeToFirstTokenMs: generation.latency,
generationTimeMs: generation.generationTime,
promptTokens: generation.promptTokens,
completionTokens: generation.completionTokens,
reasoningTokens: generation.reasoningTokens,
cachedTokens: generation.cachedTokens,
finishReason: generation.finishReason,
routing: gatewayMetadata?.routing,
},
null,
2,
),
);Usage events are ingested asynchronously, so the lookup retries HTTP 404 responses while the record becomes available. Check the error's statusCode instead of matching its message, which the SDK can normalize. The routing object includes provider attempts and any attempt errors returned in the response metadata. Generation lookup returns completed generation details. To inspect a request that fails before returning response metadata, use AI Gateway request logs or trace drains.
The AI SDK maps the common generation fields to camelCase. Use the REST response when you need its additional cost breakdown, including market_cost, surcharge_cost, and gateway_cost.
Was this helpful?