diff --git a/docs.json b/docs.json index 67609fe4..b3467ad7 100644 --- a/docs.json +++ b/docs.json @@ -112,6 +112,7 @@ "docs/learning-how-tos/cookbook/java-document-translator", "docs/learning-how-tos/cookbook/usage-analytics-dashboard", "docs/learning-how-tos/cookbook/sending-custom-reporting-tags-from-client-libraries", + "docs/learning-how-tos/cookbook/api-usage-logger", "docs/learning-how-tos/examples-and-guides/deepl-mcp-server-how-to-build-and-use-translation-in-llm-applications", "docs/learning-how-tos/cookbook/google-sheets" ] diff --git a/docs/learning-how-tos/cookbook/api-usage-logger.mdx b/docs/learning-how-tos/cookbook/api-usage-logger.mdx new file mode 100644 index 00000000..4fbdc213 --- /dev/null +++ b/docs/learning-how-tos/cookbook/api-usage-logger.mdx @@ -0,0 +1,39 @@ +--- +title: "API Usage Logger" +description: "Learn how to capture per-request DeepL API usage data and visualize it in a local dashboard." +public: true +--- + + + DeepL API Usage Logger on GitHub + + + +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/organization-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 + + + Usage tab showing total billed characters, requests, and language pair breakdown + + + + Errors tab showing failed requests grouped by error code and HTTP status + + + + SQL Explorer tab for running arbitrary DuckDB queries against the translation usage table + diff --git a/docs/learning-how-tos/cookbook/images/api-usage-logger-errors-tab.png b/docs/learning-how-tos/cookbook/images/api-usage-logger-errors-tab.png new file mode 100644 index 00000000..5abea252 Binary files /dev/null and b/docs/learning-how-tos/cookbook/images/api-usage-logger-errors-tab.png differ diff --git a/docs/learning-how-tos/cookbook/images/api-usage-logger-sql-explorer-tab.png b/docs/learning-how-tos/cookbook/images/api-usage-logger-sql-explorer-tab.png new file mode 100644 index 00000000..c740880d Binary files /dev/null and b/docs/learning-how-tos/cookbook/images/api-usage-logger-sql-explorer-tab.png differ diff --git a/docs/learning-how-tos/cookbook/images/api-usage-logger-usage-tab.png b/docs/learning-how-tos/cookbook/images/api-usage-logger-usage-tab.png new file mode 100644 index 00000000..3d8c1144 Binary files /dev/null and b/docs/learning-how-tos/cookbook/images/api-usage-logger-usage-tab.png differ diff --git a/docs/learning-how-tos/cookbook/usage-analytics-dashboard.mdx b/docs/learning-how-tos/cookbook/usage-analytics-dashboard.mdx index 00793ec4..b860c796 100644 --- a/docs/learning-how-tos/cookbook/usage-analytics-dashboard.mdx +++ b/docs/learning-how-tos/cookbook/usage-analytics-dashboard.mdx @@ -15,6 +15,8 @@ The dashboard is designed to be lightweight and easy to set up, with zero NPM de For more information about the DeepL Admin API endpoint, check out the [Admin API documentation](/api-reference/admin-api/organization-usage-analytics). +If you need per-request logging instead of account-wide views, see the [API Usage Logger](/docs/learning-how-tos/cookbook/api-usage-logger) cookbook. + ## Features - **Interactive charts and visualizations** - View your usage data through multiple chart types diff --git a/docs/resources/roadmap-and-release-notes.mdx b/docs/resources/roadmap-and-release-notes.mdx index 184a2ae3..7ba43180 100644 --- a/docs/resources/roadmap-and-release-notes.mdx +++ b/docs/resources/roadmap-and-release-notes.mdx @@ -11,6 +11,10 @@ rss: true +## May 26 - API Usage Logger Cookbook +- Added a new cookbook, [API Usage Logger](/docs/learning-how-tos/cookbook/api-usage-logger), showing how to capture per-request DeepL API usage data (billed characters, language pairs, reporting tags, API keys, errors) and explore it through a local Streamlit dashboard. +- Source code on GitHub: [`DeepLcom/deepl-api-usage-logger`](https://github.com/DeepLcom/deepl-api-usage-logger). + ## May 20 - Custom Tag Usage Analytics - Added [`GET /v2/admin/analytics/custom-tags`](/api-reference/admin-api/organization-usage-analytics) to the Admin API, allowing admins to retrieve usage statistics broken down by custom tags. - Supports `aggregate_by=period` (default) to aggregate usage over the full date range, or `aggregate_by=day` for daily breakdowns.