Get granular API usage reporting with the Show Billed Characters feature
What you’ll learn about the Show Billed Characters feature:
- DeepL API users can now report on the number of characters billed for each successful API request
- Users can now gain immediate access to API usage data from the API response
- Usage data can be used in custom reporting workflows directly from the API
The DeepL API has always placed reporting and analysis as a priority for developers and businesses like yours, whether that’s through the /usage endpoint directly in the API itself or through the recently released reporting functionality for Multiple API Keys.
Our team has just released the newest feature to add to our growing list of reporting tools: the Show Billed Characters feature, now available to all API customers.
This new feature adds to the DeepL API’s growing reporting functionality, now enabling a granular view of how many characters are being billed in the response data of each API request.
What is the Show Billed Characters feature?
Until now, API users wanting to get accurate usage data directly from the DeepL API had a single option for calling the /usage endpoint. While this is a powerful way of retrieving the most up-to-date character usage for the current billing period, it doesn’t give an accurate breakdown of the characters being translated in each request.
A new optional parameter solves this problem by returning the number of characters translated and billed with the response of each successful API request.
How does the Show Billed Characters feature work?
API customers making requests directly to the API (e.g., via a cURL command) can add the new parameter show_billed_characters to their API requests in order to receive the number of characters billed as part of the response data. API responses with a character cost involved will then return a new integer value in the format “billed_characters:50” with every response.
This value can be tracked on the API consumer’s end to be used in reporting workflows and to keep track of the cost of each individual API request.
This is especially important for requests containing structured content like HTML or XML where it may be difficult to identify the translatable characters.
At some point in future, we intend to include billed_characters in the API response by default, at which point it will be necessary to set show_billed_characters to “false” in order to not include “billed_characters” in the API response.
How does it look using the parameter?
Currently, when sending a request to the API, you get a response similar to this:
If you send a request using the new show_billed_characters parameter, your response will look like this:
Why did we launch the Show Billed Characters feature?
A number of customers have requested this feature, which enables them to report character billing in a granular way that also integrates directly into their own reporting tools with each successful API translation request.
The show_billed_characters parameter is fully operational within the API for our users — no additional setup is required. Additionally, our API documentation has been updated to reflect this change, making it easy for developers to integrate this feature into their workflows and to start benefiting from enhanced translation accuracy.
Appendix/references
https://developers.deepl.com/docs/api-reference/translate#request-body-descriptions
https://developers.deepl.com/docs/resources/release-notes#q3-2024