OpenAI and Claude Usage Report Generator

A CLI tool and library for generating billing reports from the OpenAI or Claude (Anthropic) cost APIs. Outputs Markdown (readable) and CSV (data) reports.

Can be used as:
- CLI tool: Run reports from the command line
- Library: Import functions programmatically in your Node.js/TypeScript projects

Features

- Fetches usage/cost data from OpenAI's organization costs API or Anthropic's Usage and Cost API
- Generates detailed Markdown reports with summaries and breakdowns
- Exports CSV data for further analysis
- Exports JSON data for programmatic consumption
- Daily and line-item cost breakdowns

Prerequisites

- Node.js 18+ and Yarn (.nvmrc specifies 22)
- OpenAI: Admin API key (not a standard API key), Organization ID, and Project ID
- ⚠️ Important: Standard API keys do not work. You need an admin key with organization access.
- Create one in OpenAI Platform → Settings → Organization → API keys
- Claude: Anthropic Admin API key (sk-ant-admin...)
- ⚠️ Important: Standard API keys do not work. You need an admin key.
- Create one in Console → Settings → Admin keys

Installation

$3

``bash
git clone
cd openai-and-claude-usage-report-generator
yarn install
`

$3

`bash
yarn add @ericdahl.dev/openai-and-claude-usage-report-generator


or


npm install @ericdahl.dev/openai-and-claude-usage-report-generator
`

Configuration

Create a .env file in the root directory (see .env.example for a template).

⚠️ Important: Both platforms require admin/administrative API keys. Standard API keys will not work.

OpenAI (default):

`env
OPENAI_ADMIN_KEY=sk-... # Must be an admin key, not a standard API key
OPENAI_ORG_ID=org-...
OPENAI_PROJECT_ID=proj_...
`

Claude:

`env
ANTHROPIC_ADMIN_API_KEY=sk-ant-admin-... # Must be an admin key (starts with sk-ant-admin), not a standard API key
`

Usage

$3

Generate a report for a date range. Default provider is OpenAI.

`bash
yarn report 2024-01-01 2024-01-31
yarn report 2024-01-01 2024-01-31 --provider openai
yarn report 2024-01-01 2024-01-31 --provider claude
`

$3

Import and use the functions programmatically in your code:

`typescript
import {
fetchOpenAICosts,
fetchClaudeCosts,
aggregateCosts,
generateMarkdownReport,
generateCSVReport,
generateJSONReport,
writeReports,
parseDate,
validateDateRange,
loadConfig,
} from '@ericdahl.dev/openai-and-claude-usage-report-generator';
import type { OpenAIReportConfig, ClaudeReportConfig } from '@ericdahl.dev/openai-and-claude-usage-report-generator';

// Example: Fetch and process OpenAI costs
// Note: OPENAI_ADMIN_KEY must be an admin key, not a standard API key
async function generateOpenAIReport() {
const config: OpenAIReportConfig = {
provider: 'openai',
startDate: '2024-01-01',
endDate: '2024-01-31',
apiKey: process.env.OPENAI_ADMIN_KEY!, // Must be an admin key
orgId: process.env.OPENAI_ORG_ID!,
projectId: process.env.OPENAI_PROJECT_ID!,
};

// Fetch cost data
const buckets = await fetchOpenAICosts(config);

// Aggregate the data
const aggregated = aggregateCosts(
buckets,
config.startDate,
config.endDate,
config.projectId
);

// Generate reports
const markdown = generateMarkdownReport(aggregated, config.orgId, 'openai');
const csv = generateCSVReport(aggregated);
const json = generateJSONReport(aggregated, config.orgId, 'openai');

// Or write directly to files
const { mdPath, csvPath, jsonPath } = writeReports(aggregated, config.orgId, 'openai');

console.log(Reports written to ${mdPath}, ${csvPath}, and ${jsonPath});
}

// Example: Fetch and process Claude costs
// Note: ANTHROPIC_ADMIN_API_KEY must be an admin key (sk-ant-admin...), not a standard API key
async function generateClaudeReport() {
const config: ClaudeReportConfig = {
provider: 'claude',
startDate: '2024-01-01',
endDate: '2024-01-31',
apiKey: process.env.ANTHROPIC_ADMIN_API_KEY!, // Must be an admin key (starts with sk-ant-admin)
};

const buckets = await fetchClaudeCosts(config);
const aggregated = aggregateCosts(buckets, config.startDate, config.endDate, 'default');
const markdown = generateMarkdownReport(aggregated, 'default', 'claude');

console.log(markdown);
}
`

Note: When using as a library, you need to handle environment variables yourself. The loadConfig function is available but requires environment variables to be set, or you can construct the config objects directly as shown above.

⚠️ Important Reminder: Both platforms require admin/administrative API keys. Standard API keys will not work for accessing cost/usage data.

Output

- OpenAI: reports/openai/
- Claude: reports/claude/

Each run produces:

- usage-YYYY-MM-DD-to-YYYY-MM-DD.md – Human-readable Markdown report
- usage-YYYY-MM-DD-to-YYYY-MM-DD.csv – CSV data export
- usage-YYYY-MM-DD-to-YYYY-MM-DD.json – JSON data export for programmatic consumption

Report Contents

The Markdown report includes:

- Summary: Total cost, billing days, average daily cost
- Cost by Model/Service: Breakdown by line item with percentages
- Daily Usage Breakdown: Detailed daily costs by model/service
- Total by Day: Daily totals for quick overview

The CSV export contains:
- Date, line item, cost (USD), and project ID for each entry

The JSON export contains:
- Metadata (provider, billing period, project/organization IDs, generation timestamp)
- Summary (total cost, billing days, average daily cost)
- Costs by line item (sorted by cost, includes percentages)
- Daily breakdown (all daily costs by date and line item)
- Daily totals (aggregated totals per day)

API Reference

$3

#### fetchOpenAICosts(config: OpenAIReportConfig): Promise
Fetches cost data from OpenAI's organization costs API. Returns an array of cost buckets.

#### fetchClaudeCosts(config: ClaudeReportConfig): Promise
Fetches cost data from Anthropic's cost report API. Returns an array of cost buckets (normalized to match OpenAI format).

#### aggregateCosts(buckets: CostBucket[], startDate: string, endDate: string, projectId: string): AggregatedCosts
Aggregates cost buckets into a structured format with totals, daily breakdowns, and line item summaries.

#### generateMarkdownReport(aggregated: AggregatedCosts, orgId: string, provider: 'openai' | 'claude'): string
Generates a human-readable Markdown report from aggregated costs.

#### generateCSVReport(aggregated: AggregatedCosts): string
Generates a CSV report from aggregated costs.

#### generateJSONReport(aggregated: AggregatedCosts, orgId: string, provider: 'openai' | 'claude'): string
Generates a JSON report from aggregated costs. Returns a formatted JSON string with metadata, summary, costs by line item, daily breakdown, and daily totals.

#### writeReports(aggregated: AggregatedCosts, orgId: string, provider: Provider, baseDir?: string): { mdPath: string; csvPath: string; jsonPath: string }
Writes Markdown, CSV, and JSON reports to disk. Returns paths to the generated files.

$3

#### parseDate(dateStr: string): Date
Parses a date string in YYYY-MM-DD format and returns a Date object.

#### validateDateRange(start: Date, end: Date): void
Validates that the end date is after the start date. Throws an error if invalid.

#### loadConfig(startDate: string, endDate: string, provider: Provider): ReportConfig
Loads configuration from environment variables. Requires appropriate env vars to be set based on provider.

$3

All TypeScript types are exported. Key types include:
- OpenAIReportConfig - Configuration for OpenAI API
- ClaudeReportConfig - Configuration for Claude API
- AggregatedCosts - Aggregated cost data structure
- CostBucket - Individual cost bucket from API
- DailyCost - Daily cost entry
- Provider - Union type: 'openai' | 'claude'

Development

$3

`bash
yarn test # watch mode
yarn test:run # single run (used by CI)
`

$3

`bash
yarn build
`

$3

GitHub Actions runs on push and pull requests to main: yarn install --frozen-lockfile, yarn test:run, then yarn build`. See .github/workflows/ci.yml.