Usage

Methods

Usage tracking

// Get aggregated usage summary (by model and day)
const summary = await client.usage.summary();
// { totalCostCents, totalRequests, totalInputTokens, totalOutputTokens, byModel, byDay }

// List individual usage logs (paginated)
const logs = await client.usage.list();
// { items: [{ id, model, input_tokens, output_tokens, cost_cents, duration_ms, ... }], nextCursor, hasMore }

// Get a single usage log with full request/response bodies
const detail = await client.usage.get('log-id');
// { ...log, request_body: string | null, response_body: string | null }

API keys

// List your API keys (paginated)
const keys = await client.apiKeys.list();
// { items: [{ id, name, key_prefix, last_used_at, created_at }], nextCursor, hasMore }

// Create a new API key (raw key returned only once)
const newKey = await client.apiKeys.create('My Script');
// { id, name, key, key_prefix, created_at }

// Delete an API key
await client.apiKeys.delete('key-id-here');

Profile

// Get your own profile
const me = await client.users.me();
// { id, email, name, created_at, updated_at }

// Update your display name
const updated = await client.users.updateMe({ name: 'New Name' });

Health

const status = await client.health();
// { status: 'ok', dbLatencyMs: 2 }

Error handling

The SDK throws SdkError for non-2xx responses:

import { createClient, SdkError } from '@codecosts/sdk';

const client = createClient({
  baseUrl: 'https://codecosts.com',
  apiKey: 'sk_...',
});

try {
  await client.usage.summary();
} catch (err) {
  if (err instanceof SdkError) {
    console.log(err.status);  // HTTP status code (e.g. 401)
    console.log(err.message); // Error message from server
    console.log(err.body);    // Full response body
  }
}

Common errors

Status	Cause	Fix
401	API key invalid or missing	Check your API key is correct
429	Rate limited	Wait err.body.retryAfter seconds and retry

TypeScript

All methods are fully typed. Request and response types are inferred from the Zod schemas in shared/src/types/api.ts:

import type { UsageSummaryResponse, UsageLogDetailResponse } from '@codecosts/shared';

// client.usage.summary() returns Promise<UsageSummaryResponse>
// client.usage.get(id) returns Promise<UsageLogDetailResponse>