Cursor Usage Report Generator

A Python tool to analyze and generate comprehensive markdown reports from Cursor IDE usage data exported as CSV files.

Table of Contents

• Features
• Requirements
• Installation
• Usage
  • Basic Usage
  • Customizing File Names
• Report Structure
  • Summary
  • Usage by Model
  • Usage by Kind
  • Token Efficiency
• Example Output
• CSV Format
• Data Filtering
• Project Structure
• Exporting Data from Cursor
• Contributing
• License
• Acknowledgments
• Support

Features

• 📊 Comprehensive Analytics: Analyze usage data including requests, costs, and token usage
• 🔍 Model Breakdown: Detailed statistics per AI model used
• 📈 Usage by Kind: Breakdown by usage type (Included, On-Demand, Free, etc.)
• 💰 Cost Analysis: Track total costs and cost per request/token
• 🚀 Token Efficiency Metrics: Cache hit rates and token usage statistics
• 🧹 Automatic Filtering: Filters out errored/no-charge events automatically
• 📅 Date Range Tracking: Automatically detects and reports date ranges in your data

Requirements

• Python 3.6 or higher
• No external dependencies (uses only Python standard library)

Installation

1. Clone or download this repository
2. Ensure you have Python 3.6+ installed
3. No additional packages required - uses only Python standard library

Usage

Basic Usage

1. Export your usage data from Cursor:

   • Go to Cursor dashboard
   • Export usage events as CSV
   • Save the file as usage-events-2025.csv (or update the filename in the script)

2. Run the script:

python3 generate_usage_report.py

3. The report will be generated as usage_report_2025.md

Customizing File Names

Edit the constants at the top of generate_usage_report.py:

CSV_FILE = "usage-events-2025.csv"      # Your input CSV file
REPORT_FILE = "usage_report_2025.md"     # Output report file

Report Structure

The generated markdown report includes:

Summary

• Total requests
• Total cost
• Token statistics (input, output, cache read, total)

Usage by Model

• Breakdown of usage per AI model
• Requests, costs, and token usage per model
• Sorted by cost (highest first)

Usage by Kind

• Breakdown by usage type:
  • Included (subscription credits)
  • On-Demand (pay-as-you-go)
  • Free
  • Aborted/Not Charged
  • User API Key

Token Efficiency

• Cache hit rate percentage
• Average tokens per request
• Average cost per request
• Cost per 1M tokens

Example Output

# Cursor Usage Report 2025

Generated on: 2025-12-23 14:30:00

**Date Range:** 2025-01-02 to 2025-12-23

## Summary

- **Total Requests:** 127,543
- **Total Cost:** $12,847.32
- **Total Input Tokens:** 1,234,567,890
- **Total Output Tokens:** 234,567,890
- **Total Cache Read Tokens:** 8,765,432,109
- **Total Tokens:** 10,234,567,889

## Usage by Model

| Model | Requests | Cost | Input Tokens | Output Tokens | Cache Read | Total Tokens |
|-------|----------|------|--------------|---------------|------------|--------------|
| claude-4.5-opus-high-thinking | 8,234 | $4,567.89 | 456,789,012 | 78,901,234 | 3,456,789,012 | 3,992,479,258 |
| claude-4.5-sonnet-thinking | 12,456 | $3,234.56 | 345,678,901 | 67,890,123 | 2,345,678,901 | 2,759,247,925 |
| claude-4-sonnet-thinking | 18,765 | $2,345.67 | 234,567,890 | 56,789,012 | 1,234,567,890 | 1,525,924,792 |
| gemini-3-pro-preview | 3,421 | $1,234.56 | 123,456,789 | 45,678,901 | 567,890,123 | 737,025,813 |
| gpt-5 | 5,678 | $567.89 | 67,890,123 | 34,567,890 | 456,789,012 | 559,247,025 |
| claude-4-sonnet | 4,321 | $234.56 | 45,678,901 | 23,456,789 | 345,678,901 | 414,814,591 |
| auto | 2,345 | $123.45 | 34,567,890 | 12,345,678 | 234,567,890 | 281,481,458 |
...

## Usage by Kind

| Kind | Requests | Cost |
|------|----------|------|
| Included | 89,234 | $8,234.56 |
| On-Demand | 35,678 | $4,234.56 |
| free | 456 | $234.56 |
| Free | 123 | $123.45 |
| Aborted, Not Charged | 56 | $0.00 |
| User API Key | 12 | $0.00 |

## Token Efficiency

- **Cache Hit Rate:** 85.64%
- **Average Tokens per Request:** 80,234
- **Average Cost per Request:** $0.1007
- **Cost per 1M Tokens:** $1.26

CSV Format

The script expects a CSV file with the following columns:

• Date: ISO 8601 timestamp
• Kind: Usage type (Included, On-Demand, Free, Errored No Charge, etc.)
• Model: AI model name
• Max Mode: Whether max mode was used
• Input (w/ Cache Write): Input tokens with cache writes
• Input (w/o Cache Write): Input tokens without cache writes
• Cache Read: Cache read tokens
• Output Tokens: Output tokens generated
• Total Tokens: Total tokens used
• Cost: Cost in USD

Data Filtering

The script automatically filters out rows where Kind contains "Errored, No Charge" to provide accurate cost and usage statistics.

Project Structure

.
├── generate_usage_report.py    # Main script
├── README.md                    # Project documentation
├── LICENSE                      # MIT License
├── CONTRIBUTING.md              # Contribution guidelines
├── .gitignore                   # Git ignore rules
├── usage-events-2025.csv       # Input CSV file (your data, not in repo)
└── usage_report_2025.md        # Generated report (not in repo)

Exporting Data from Cursor

To export your usage data from Cursor:

1. Log in to your Cursor account
2. Navigate to the dashboard/usage section
3. Select the date range you want to analyze
4. Export as CSV with the "tokens" strategy
5. Save the file as usage-events-2025.csv (or your preferred name)

The export URL format is:

https://cursor.com/api/dashboard/export-usage-events-csv?startDate={startTimestamp}&endDate={endTimestamp}&strategy=tokens

Full Year 2025 URL:

https://cursor.com/api/dashboard/export-usage-events-csv?startDate=1735689600000&endDate=1767225599999&strategy=tokens

This URL will export all usage data from January 1, 2025 00:00:00 UTC to December 31, 2025 23:59:59.999 UTC.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Some areas for improvement:

• Support for multiple CSV files
• Additional visualization options
• Export to other formats (JSON, HTML)
• Monthly/yearly breakdowns
• Cost forecasting
• Model performance comparisons

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Cursor IDE for providing usage data export functionality

Support

If you find this project useful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs
• 💡 Suggesting new features
• 🔧 Contributing improvements

---

Made with ❤️ for the Cursor IDE community