API ReferenceTranslate

Get Document Translation

Get the translation for a target language and style, including current status, remaining billable words, estimated API cost, and translated content. The service rebuilds the document's current paragraphs or pages and compares their hashes with the hashes stored during translation. Changed source content is returned as stale and becomes billable again when translation is requested.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

document_idUUIDRequired
Stable document ID.
target_languageenumRequired

Target language used when the translation was created, or auto for automatic direction selection.

Allowed values:

Query parameters

translation_stylestringOptional

Translation style ID. Built-ins are default, learning_english for an English target, and sefer_hebrew for a Hebrew target. Omit this to use default. Custom style IDs come from /v1/translation-styles.

Response

This endpoint returns an object.
document_idUUID
Stable source document ID.
target_languageenum

Requested translation language. With auto, each segment reports its concrete language in its own target_language field.

Allowed values:
translation_stylestring

Translation style ID used for this independently stored target-language translation.

statusstring
Overall translation status.
completed_segmentsinteger
Number of successfully translated paragraphs or pages.
failed_segmentsinteger
Number of failed paragraphs or pages.
source_word_countinteger
Total visible words across the document's current paragraphs or pages, including content that already has a current translation.
billable_word_countinteger

Words in missing, failed, forced, or stale segments that still need translation. Cached current segments are excluded, so this can be zero even when source_word_count is not.

estimated_api_cost_centsdouble

Estimated API balance reservation for the current billable_word_count, in cents, at USD 0.25 per 1,000 words. For example, 25 means USD 0.25 and 250 means USD 2.50. This is an estimate of remaining work, not a historical invoice, and normally becomes zero after all current segments are translated.

segmentslist of objects

Paragraph- or page-level results for this target language and translation style.

total_segmentsintegerOptional
Total paragraphs or pages in the translation job.
created_atdatetimeOptional
When the translation job was created.
updated_atdatetimeOptional
When the translation job was last updated.
errorstringOptional
Overall job error, if any.

Errors

401
Authentication Error
404
Document Not Found
429
Rate Limit Error