diff --git a/docs.json b/docs.json index 94771ad2..be572561 100644 --- a/docs.json +++ b/docs.json @@ -110,6 +110,7 @@ "docs/learning-how-tos/cookbook/nodejs-proxy", "docs/learning-how-tos/cookbook/java-document-translator", "docs/learning-how-tos/cookbook/usage-analytics-dashboard", + "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..6bc53dfb --- /dev/null +++ b/docs/learning-how-tos/cookbook/api-usage-logger.mdx @@ -0,0 +1,38 @@ +--- +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 +- **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