DeepL Usage Dashboard

A demo dashboard for visualizing DeepL API key usage across an entire account, powered by a single API call to the /v2/admin/analytics endpoint. For more info about the DeepL Admin endpoint, check out our help pages or the Admin API spec.

Features

• Interactive charts and visualizations
• Flexible date ranges (rolling period or a fixed date range)
• Per-API-key breakdown
• Basic trends and forecasting
• Secure local configuration
• Zero NPM dependencies (Chart.js loaded from CDN)
• Sample data included for testing and demos

Screenshots

Prerequisites

• Node.js v16+
• DeepL Admin API key see info

Quick Start

Demo Mode

Run the dashboard with sample data:

npm run sample

We've included some preconfigured sample data so you can explore the dashboard's features. This requires no configuration or API key.

---

Full Setup

1. Clone & Install

git clone https://github.com/DeepLcom/usage-analytics-demo-dashboard.git
cd usage-analytics-demo-dashboard
npm install

Note: This project has no runtime dependencies. Chart.js is loaded from CDN.

2. Setup

Run the interactive setup:

npm run setup

Required inputs:

• DeepL Admin API key (format: xxxxx:adm)
• Date range option:
  • Rolling period (default): Last N days (defaults to 30)
  • Fixed date range: Specific start and end dates (YYYY-MM-DD)
• Server port (default: 3000)

API endpoint defaults to https://api.deepl.com. For normal DeepL API users you won't have to change this value.

Creates config.json with the configured settings.

3. Fetch Data

Fetch usage data from the DeepL API:

npm run fetch

The dashboard makes a single API call using group_by=key_and_day to get all data, then aggregates it locally to create the different views (by key, by day, and total).

4. Start Dashboard

Start the server:

npm start

Server automatically finds an available port, starting at 3000 and moving up if that one is busy.

Access the dashboard at the displayed URL (typically http://localhost:3000).

---

Available Commands

Command	Description
npm run setup	Interactive setup for the config file
npm run fetch	Fetch usage from API.
npm start	Start the dashboard server
npm run sample	Start server with sample data (no config required)
npm run dev	Fetch data then start server (one command)

---

Using Sample Data

The repository includes sample data with realistic usage patterns.

Quick start:

npm run sample

This starts the dashboard at http://localhost:3000 using sample data (no configuration needed).

Alternative method:

Set "use_sample_data": true in config.json and run npm start

---

Configuration

Example Configuration

Copy config.json.example to config.json and customize:

{
    "deepl": {
        "admin_api_key": "YOUR_ADMIN_API_KEY_HERE",
        "base_url": "https://api.deepl.com"
    },
    "data": {
        "range_type": "rolling",
        "days_back": 30,
        "output_directory": "./data",
        "use_sample_data": false
    },
    "server": {
        "port": 3000,
        "host": "0.0.0.0"
    }
}

Security Warning

⚠️ Important: Never commit the config.json file to public repositories.

Your config.json file contains sensitive credentials (Admin API key). Always ensure this file is listed in .gitignore before committing code to version control. Accidental exposure of your API key could lead to unauthorized usage of your DeepL account.

Configuration Options

Field	Description	Default
deepl.admin_api_key	Your DeepL admin API key	-
deepl.base_url	DeepL API endpoint	https://api.deepl.com
data.range_type	Date range mode: "rolling" or "fixed"	"rolling"
data.days_back	Days of historical data (rolling mode only)	30
data.start_date	Start date in YYYY-MM-DD format (fixed mode only)	-
data.end_date	End date in YYYY-MM-DD format (fixed mode only)	-
data.output_directory	Where to save fetched data	./data
data.use_sample_data	Use sample data instead of live data	false
server.port	Dashboard server port (with auto-fallback)	3000
server.host	Dashboard server host	127.0.0.1

Date Range Options

Rolling Period (Recommended):

"data": {
  "range_type": "rolling",
  "days_back": 30
}

• Fetches the last N days of data
• Updates with current data on each fetch
• Ideal for ongoing monitoring
• Dates are calculated using UTC midnight to ensure consistency regardless of server timezone

Fixed Date Range:

"data": {
  "range_type": "fixed",
  "start_date": "2025-01-01",
  "end_date": "2025-01-31"
}

• Fetches data for specific date range
• Use for monthly reports, audits, or historical analysis
• Dates in ISO 8601 format (YYYY-MM-DD)
• All dates are interpreted as UTC midnight

---

Refreshing Data

Update the dashboard with latest data:

npm run fetch

Refresh the browser to view updated data. The dashboard displays a "last updated" timestamp.

Behavior:

• Rolling period: Fetches the most recent N days
• Fixed date range: Re-fetches the configured date range

Data Accuracy

Note: This dashboard is for informational purposes. Data shown here may differ from your official usage records due to local caching if data is not refreshed. Your monthly invoice remains the final source of truth for billing.

---

License

MIT (see LICENSE file)