> ## Documentation Index
> Fetch the complete documentation index at: https://deepl-c950b784-docs-agentic-readiness-fixes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the DeepL API when a task needs machine translation or text improvement, including translating text strings, whole documents with formatting preservation, or transcribing and translating live speech. Preferred terminology and phrasing may be enforced using customizations (glossaries, style rules, and translation memories). Retrieve supported languages for each product from the `/v3/languages` endpoints.
> Read the machine-readable API surface instead of inferring request shapes from prose: the REST spec is at https://developers.deepl.com/api-reference/openapi.yaml (also served as openapi.json) and the Voice WebSocket protocol is at https://developers.deepl.com/api-reference/voice/voice.asyncapi.yaml. These docs also expose an MCP server at https://developers.deepl.com/mcp (Streamable HTTP, no authentication).
> Use https://api.deepl.com for Pro plans and https://api-free.deepl.com for the Free plan. Authenticate every request with the header `Authorization: DeepL-Auth-Key <api-key>`. Never fabricate an API key: ask the user for one, or point them at https://developers.deepl.com/docs/getting-started/quickstart.
> Errors use standard HTTP status codes with a JSON body containing a `message` field, plus a `code` field where available, and an `X-Trace-ID` response header that identifies the request in DeepL's logs. Log `X-Trace-ID` by default. Retry 429 and 5xx with exponential backoff. Do not retry 456, which means the account quota is exhausted, or 400, which means the request itself is invalid.

# API Usage Logger

> Learn how to capture per-request DeepL API usage data and visualize it in a local dashboard.

<Card title="GitHub - DeepL/deepl-api-usage-logger" icon="github" horizontal href="https://github.com/DeepL/deepl-api-usage-logger">
  DeepL API Usage Logger on GitHub
</Card>

This open-source reference project shows how to capture per-request usage data for the DeepL API (billed characters, language pairs, reporting tags, API key identifiers, and errors) and explore it through a local Streamlit dashboard. It wraps the [DeepL Python client](/docs/getting-started/client-libraries) so every text and document translation request is logged to a local DuckDB file as it happens, alongside any errors returned by the API.

The project is intended for teams that need usage reporting with request-level granularity. If you instead want to retrieve subscription-level or API key-level data via a single API call, see the [Usage Analytics Dashboard](/docs/learning-how-tos/cookbook/usage-analytics-dashboard) cookbook, which uses the [Admin API](/api-reference/admin-api/get-usage-analytics).

## Features

* **Per-request logging** for both text and document translation, with the source language, target language, billed characters, and a request ID stored for every call
* **Text translation requests with multiple texts** produce one row per text, all sharing the same `request_id`, so the language and character breakdown of each text within a multi-text request stays visible
* **Error capture alongside successes**, including the error code, HTTP status, and message, so reliability and usage live in the same dataset
* **Reporting tag and API key alias support**, letting you group usage by team, project, or service
* **Streamlit dashboard** with three views: a Usage summary table, an Error summary table, and a SQL Explorer for arbitrary DuckDB queries against the underlying table
* **CSV export** from every dashboard view
* **Non-blocking writes** that queue log entries on a background thread, so logging never adds latency to translation calls
* **Local stack** of Python, DuckDB, and Streamlit, with no external services required

## Screenshots

<Frame>
  <img src="https://mintcdn.com/deepl-c950b784-docs-agentic-readiness-fixes/A7qtSjBxGPa9Sib6/docs/learning-how-tos/cookbook/images/api-usage-logger-usage-tab.png?fit=max&auto=format&n=A7qtSjBxGPa9Sib6&q=85&s=c9a2c1091b9a42f9349273f68f3ba5ff" alt="Usage tab showing total billed characters, requests, and language pair breakdown" width="1678" height="1608" data-path="docs/learning-how-tos/cookbook/images/api-usage-logger-usage-tab.png" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/deepl-c950b784-docs-agentic-readiness-fixes/A7qtSjBxGPa9Sib6/docs/learning-how-tos/cookbook/images/api-usage-logger-errors-tab.png?fit=max&auto=format&n=A7qtSjBxGPa9Sib6&q=85&s=c6bad18f2146fb2c3577aae1fcce435b" alt="Errors tab showing failed requests grouped by error code and HTTP status" width="1686" height="1274" data-path="docs/learning-how-tos/cookbook/images/api-usage-logger-errors-tab.png" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/deepl-c950b784-docs-agentic-readiness-fixes/A7qtSjBxGPa9Sib6/docs/learning-how-tos/cookbook/images/api-usage-logger-sql-explorer-tab.png?fit=max&auto=format&n=A7qtSjBxGPa9Sib6&q=85&s=02f88de83b12cfb2e289678168e9cf54" alt="SQL Explorer tab for running arbitrary DuckDB queries against the translation usage table" width="1694" height="1370" data-path="docs/learning-how-tos/cookbook/images/api-usage-logger-sql-explorer-tab.png" />
</Frame>