Estimate translation work
Preview the work and approximate cost of a document submission before creating a translation job.
Estimate a job when you need to inspect its selected work or likely usage before translation. The endpoint plans the documents against the engine's current configuration without creating a job or executing the pipeline.
Request an estimate #
POST /v2/organizations/:orgId/localization/estimates
Content-Type: application/json
X-API-Key: YOUR_API_KEYUse the same engineId, sourceLocale, targetLocales, and documents fields as job creation. Inline JSON, artifact addresses, previous sources, and previous translations are supported. Omit job-only options such as originId.
{
"engineId": "YOUR_ENGINE_ID",
"sourceLocale": "en",
"targetLocales": ["es"],
"documents": [
{
"key": "messages.json",
"format": { "type": "json" },
"source": { "content": { "save": "Save changes", "cancel": "Cancel" } }
}
]
}The request supports at most 100 documents and 100 distinct target locales, including per-document overrides. Planning is also bounded by 25 MiB of input, 20,000 source units, and 20,000 pending translations. Split larger work into smaller estimates. EstimateTooLarge identifies the exceeded limit; EstimateDocumentInvalid identifies a document that cannot be parsed or aligned.
Supply missing files #
HTTP 200 can return "_tag": "MissingArtifacts" with an uploads array. Upload each address's original bytes to its returned uploadUrl using an authenticated PUT, then repeat the estimate request. These are organization artifact uploads; no job is created.
For inline-only input, the estimate reads the supplied JSON directly. Estimation still sends content to Lingo.dev; it is not an offline check.
Read the estimate #
A ready response has "_tag": "Estimated" and approximate: true:
| Field | Meaning |
|---|---|
work | Counts of sourceUnits, pendingTranslations, and reusedTranslations. |
totals | Planned token and cost totals. |
conditional | Separate allowances for work that depends on later outcomes. |
byLocale | Pending and reused translations, planned costs, and conditional costs for each target locale. |
stages | Stage, optional locale (null for shared work), conditional flag, unit and request counts, and estimated cost. |
exclusions | Unpriced work, such as externalHumanReview. |
warnings | Limits and assumptions relevant to this estimate. |
Each cost object contains inputTokens, outputTokens, providerCostUsd, providerDirectCostUsd, localizationCostUsd, aiReviewCostUsd, and totalCostUsd. totalCostUsd excludes provider-direct BYOK spending, conditional allowances, and external human-review fees. Read those separately when planning the workflow.
Amounts estimate usage charges before plan allowances. They are not an invoice, a spending cap, or a guaranteed upper bound. Shared source-stage work can appear with locale: null, so per-locale rows alone need not add up to the whole-job total.
After inspecting the plan, create and start a job with the intended source revision and options. The estimate reserves neither work nor pricing; changed source, guidance, models, or pipeline settings can change the eventual work.