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 #

http
POST /v2/organizations/:orgId/localization/estimates
Content-Type: application/json
X-API-Key: YOUR_API_KEY

Use 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.

json
{
  "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:

FieldMeaning
workCounts of sourceUnits, pendingTranslations, and reusedTranslations.
totalsPlanned token and cost totals.
conditionalSeparate allowances for work that depends on later outcomes.
byLocalePending and reused translations, planned costs, and conditional costs for each target locale.
stagesStage, optional locale (null for shared work), conditional flag, unit and request counts, and estimated cost.
exclusionsUnpriced work, such as externalHumanReview.
warningsLimits 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.