> ## Documentation Index
> Fetch the complete documentation index at: https://developers.deepl.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve an import or export job
> Learn how to poll a translation memory import or export job and read its status values and results.
One endpoint covers both [import](/api-reference/translation-memory/import-a-translation-memory) and [export](/api-reference/translation-memory/export-a-translation-memory) jobs. Read `operation` to tell them apart, then read `results[0]` for the status and, once the job finishes, its output.
`results` always holds exactly one entry. It is an array so that jobs producing multiple outputs can be added later without a breaking change, so index into it rather than assuming a single object.
## Status values
| **Status** | **Applies to** | **Meaning** |
| ---------------- | -------------- | -------------------------------------------------------------------------------------------------------------- |
| `awaiting_input` | Import | The job exists but the file has not been uploaded yet. `status_metadata.required_action` says what is missing. |
| `processing` | Import, export | The file was received and is being processed. |
| `completed` | Import, export | The job succeeded. Read `translation_memory_id` (import) or `download_url` (export). |
| `failed` | Import, export | The job did not finish. `error.message` says why. |
| `expired` | Import, export | The job is too old to act on. Create a new one. |
Poll until the status is `completed`, `failed`, or `expired`. The other states are transient and will change on their own.
## Which fields to expect
Fields that do not apply to a job's `operation` are omitted rather than returned as `null`, so check for a field's presence before reading it:
* **Import jobs** include `source_file` and `parameters.display_name`. On completion, the result adds `translation_memory_id` and may add `skipped_segment_count`.
* **Export jobs** include `parameters.translation_memory_id`. On completion, the result adds `download_url` and `expires_at`.
An import that sits at `awaiting_input` means DeepL is still waiting for the file. Upload it to the `upload_url` from the import response; the status will not advance on its own.
## OpenAPI
````yaml get /v3/translation_memories/jobs/{job_id}
openapi: 3.0.3
info:
title: DeepL API Documentation
description: >-
The DeepL API provides programmatic access to DeepL’s language AI
technology.
Note: this OpenAPI spec is embedded into our API documentation and has
shortened descriptions.
termsOfService: https://www.deepl.com/pro-license
contact:
name: DeepL - Contact us
url: https://www.deepl.com/contact-us
version: 3.12.0
servers:
- url: https://api.deepl.com
description: DeepL API Pro
- url: https://api-free.deepl.com
description: DeepL API Free
security: []
tags:
- name: beta
description: >-
Experimental features that are under testing and not yet intended for
production use.
- name: TranslateText
description: >-
The text-translation API currently consists of a single endpoint,
`translate`, which is described below.
- name: TranslateDocuments
description: >-
The document translation API allows you to translate whole documents and
supports the following file types and extensions:
* `docx` - Microsoft Word Document
* `pptx` - Microsoft PowerPoint Document
* `xlsx` - Microsoft Excel Document
* `pdf` - Portable Document Format
* `htm / html` - HTML Document
* `txt` - Plain Text Document
* `xlf / xliff` - XLIFF Document (versions 1.2, 2.0, and 2.1)
* `srt` - SRT Document
* `idml` - Adobe InDesign Markup Language
* `xml` - XML Document
* `json` - JSON Document
* `dita` - DITA topic (Darwin Information Typing Architecture)
* `mif` - Adobe FrameMaker Interchange Format
* `jpeg` / `jpg` / `png` - Image (currently in beta)
- name: RephraseText
description: >-
The `rephrase` endpoint is used to make corrections and adjustments to
texts based on style or tone.
- name: CorrectText
description: >-
The `correct` endpoint fixes spelling and grammar errors without broader
rephrasing. Use it when you want
a minimal-change correction pass rather than the broader rewriting
performed by `rephrase`.
- name: ManageSpokenTerms
description: >-
The *Spoken Terms* functions allow you to create, inspect, edit and delete
Spoken Terms collections.
Spoken Terms improve speech recognition in the Voice API: they ensure
specific words and phrases,
such as company names, acronyms, and product names, are transcribed
correctly. A collection contains
one or more term lists, each holding terms for a single language, and is
applied to a voice session
via the `spoken_terms_id` parameter.
- name: ManageMultilingualGlossaries
description: >-
The *glossary* functions allow you to create, inspect, edit and delete
glossaries.
Glossaries created with the glossary function can be used in translate
requests by specifying the
`glossary_id` parameter. A glossary contains (several) dictionaries.
A dictionary is a mapping of source phrases to target phrases for a single
language pair.
If you encounter issues, please let us know at support@DeepL.com.
Currently you can create glossaries with any of the languages DeepL
supports (with the exception of Thai).
The maximum size limit for a glossary is 10 MiB = 10485760 bytes and each
source/target text,
as well as the name of the glossary, is limited to 1024 UTF-8 bytes.
A total of 1000 glossaries are allowed per account.
When creating a dictionary with target language `EN`, `PT`, or `ZH`, it's
not necessary to specify a variant
(e.g. `EN-US`, `EN-GB`, `PT-PT`, `PT-BR`, or `ZH-HANS`).
Dictionaries with target language `EN` can be used in translations with
either English variant.
Similarly `PT`, and `ZH` dictionaries can be used in translations with
their corresponding variants.
(When you provide the ID of a glossary to a translation, the appropriate
dictionary is automatically applied. Currently glossaries can not yet be
used with source language detection.)
Glossaries created via the DeepL API are now unified with glossaries
created via the DeepL website and DeepL apps.
Please only use the v3 glossary API in conjunction with multilingual or
edited glossaries from the website.
- name: ManageGlossaries
description: >-
Please note that this is the spec for the (old) v2 glossary endpoint.
We recommend users switch to the newer v3 glossary endpoints, which
support editability and multilinguality.
The *glossary* functions allow you to create, inspect, and delete
glossaries.
Glossaries created with the glossary function can be used in translate
requests by specifying the
`glossary_id` parameter.
If you encounter issues, please let us know at support@DeepL.com.
Currently you can create glossaries with any of the languages DeepL
supports (with the exception of Thai).
- name: MetaInformation
description: Information about API usage and value ranges
- name: TranslationMemories
description: >-
The translation memory endpoints allow you to manage your account's
translation memories, used to store
and reuse previously created translations. You can list and retrieve
translation memories, page through
their stored segments, create one by importing a TMX file, export one back
to TMX, and delete one.
Editing the contents of an existing translation memory is not supported;
import a new one instead.
Importing and exporting run as background jobs. Create the job, then poll
`GET /v3/translation_memories/jobs/{job_id}` until it reports `completed`.
Translation memories can be used in text translation requests by
specifying the `translation_memory_id` parameter to denote a specific
translation memory and the
`translation_memory_threshold` which defines the minimum matching
percentage required for a translation memory
segment to be applied (recommended to be 75% or higher). A translation
request fails with `404` if the
translation memory does not exist or does not cover the requested language
pair.
- name: VoiceAPI
description: >-
The Voice API provides real-time voice transcription and translation
services.
Use a two-step flow: first request a streaming URL via REST, then
establish a WebSocket connection for streaming audio and receiving
transcriptions.
- name: VoiceTranslateJob
description: >-
**Alpha.** Async voice translation jobs. This API may change without
notice.
- name: AdminApi
description: >-
Endpoints for organization administrators to manage API keys and retrieve
usage analytics.
- name: QualityEvaluation
description: >-
**Closed alpha.** Evaluate translation quality. Submit source/target
segment pairs and retrieve per-segment quality issues categorized by error
type and severity, with character spans pointing to where each issue
occurs.
externalDocs:
description: DeepL Pro - Plans and pricing
url: https://www.deepl.com/pro#developer
paths:
/v3/translation_memories/jobs/{job_id}:
get:
tags:
- TranslationMemories
summary: Retrieve an import or export job
description: >-
Retrieve the status of a translation memory import or export job.
Poll this endpoint after creating a job. The `operation` field tells you
which kind of job it is,
and the single entry in `results` carries the status and, once the job
finishes, its output: the
new `translation_memory_id` for an import, or a `download_url` for an
export.
Requires an API key with the `translation_memories:read` scope.
operationId: getTranslationMemoryJob
parameters:
- name: job_id
in: path
required: true
schema:
type: string
format: uuid
description: >-
The identifier of the job, returned when you created the import or
export.
example: 0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40
responses:
'200':
description: Returns the current state of the job.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
content:
application/json:
schema:
$ref: '#/components/schemas/TranslationMemoryJob'
examples:
Import awaiting upload:
value:
job_id: 0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40
product: translation_memory
operation: import
creation_time: '2026-08-06T15:04:25.223Z'
updated_time: '2026-08-06T15:04:25.223Z'
source_file:
content_type: application/xml
content_length: 1024
parameters:
display_name: Legal
results:
- status: awaiting_input
status_metadata:
required_action: Waiting for upload
Import completed:
value:
job_id: 0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40
product: translation_memory
operation: import
creation_time: '2026-08-06T15:04:25.223Z'
updated_time: '2026-08-06T15:06:11.418Z'
source_file:
content_type: application/xml
content_length: 1024
parameters:
display_name: Legal
results:
- status: completed
translation_memory_id: a74d88fb-ed2a-4943-a664-a4512398b994
skipped_segment_count: 12
Export completed:
value:
job_id: 7c2e5a91-3b8d-4f16-8e0a-6d4c2b7f9a13
product: translation_memory
operation: export
creation_time: '2026-08-06T15:04:25.223Z'
updated_time: '2026-08-06T15:05:02.771Z'
parameters:
translation_memory_id: a74d88fb-ed2a-4943-a664-a4512398b994
results:
- status: completed
download_url: >-
https://assets.deepl.com/download/7c2e5a91-3b8d-4f16-8e0a-6d4c2b7f9a13
expires_at: '2026-08-06T16:05:02.771Z'
Failed:
value:
job_id: 0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40
product: translation_memory
operation: import
creation_time: '2026-08-06T15:04:25.223Z'
updated_time: '2026-08-06T15:04:58.102Z'
source_file:
content_type: application/xml
content_length: 1024
parameters:
display_name: Legal
results:
- status: failed
error:
message: The uploaded file is not valid TMX.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/ForbiddenScoped'
'404':
description: The job could not be found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
security:
- auth_header: []
components:
headers:
X-Trace-ID:
description: >-
A unique identifier for the request that can be included in bug reports
to DeepL support.
schema:
type: string
example: 501c3d93cc0c4f11ae2f60a226c2f0f0
schemas:
TranslationMemoryJob:
description: >-
The state of a translation memory import or export job. Fields that do
not apply to the job's
`operation` are omitted.
type: object
required:
- job_id
- product
- operation
- creation_time
- updated_time
- parameters
- results
properties:
job_id:
description: The identifier of the job.
type: string
format: uuid
example: 0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40
product:
description: The DeepL product the job belongs to. Always `translation_memory`.
type: string
example: translation_memory
operation:
description: Which kind of job this is.
type: string
enum:
- import
- export
example: import
creation_time:
description: The time the job was created, in the ISO 8601-1:2019 format.
type: string
format: date-time
example: '2026-08-06T15:04:25.223Z'
updated_time:
description: The time the job last changed state, in the ISO 8601-1:2019 format.
type: string
format: date-time
example: '2026-08-06T15:06:11.418Z'
source_file:
description: >-
The file declared when the import job was created. Omitted for
export jobs.
type: object
properties:
content_type:
description: The MIME type declared for the uploaded file.
type: string
example: application/xml
content_length:
description: The size in bytes declared for the uploaded file.
type: integer
format: int64
example: 1024
parameters:
description: >-
The parameters the job was created with. Import jobs report
`display_name`; export jobs report
`translation_memory_id`.
type: object
properties:
translation_memory_id:
$ref: '#/components/schemas/TranslationMemoryId'
display_name:
description: The name given to the translation memory the import creates.
type: string
example: Legal
results:
description: >-
The job's outcome. This array always holds exactly one entry. It is
an array so that jobs
producing multiple outputs can be represented without a breaking
change.
type: array
items:
$ref: '#/components/schemas/TranslationMemoryJobResult'
ErrorResponse:
type: object
required:
- message
properties:
message:
type: string
description: A human-readable description of the error.
code:
type: string
description: >-
A machine-readable identifier for the error, when available. Clients
should match on this value rather than on `message` when branching
on error types.
example: invalid_content_type
TranslationMemoryId:
type: string
format: uuid
description: A unique ID assigned to a translation memory.
example: a74d88fb-ed2a-4943-a664-a4512398b994
TranslationMemoryJobResult:
description: >-
The status of a translation memory job and, once it finishes, its
output.
type: object
required:
- status
properties:
status:
description: |-
The job's current state:
* `awaiting_input` - the job exists but the file has not been uploaded yet (import only)
* `processing` - the file was received and is being processed
* `completed` - the job finished successfully
* `failed` - the job did not finish; see `error`
* `expired` - the job is too old to act on; create a new one
type: string
enum:
- awaiting_input
- processing
- completed
- failed
- expired
example: completed
status_metadata:
description: >-
Extra context for states that need you to act. Present only when
there is something to do.
type: object
properties:
required_action:
description: What the job is waiting for.
type: string
example: Waiting for upload
download_url:
description: >-
A short-lived URL to download the exported TMX file from. Present on
completed export jobs
only. Download the file rather than storing this URL.
type: string
format: uri
example: >-
https://assets.deepl.com/download/7c2e5a91-3b8d-4f16-8e0a-6d4c2b7f9a13
expires_at:
description: >-
The time `download_url` stops working, in the ISO 8601-1:2019
format. Present on completed
export jobs only.
type: string
format: date-time
example: '2026-08-06T16:05:02.771Z'
error:
description: Why the job failed. Present only when `status` is `failed`.
type: object
properties:
message:
description: A description of the failure.
type: string
example: The uploaded file is not valid TMX.
translation_memory_id:
$ref: '#/components/schemas/TranslationMemoryId'
skipped_segment_count:
description: >-
How many segments in the uploaded file were not imported, for
example because they were
malformed or duplicated an existing segment. Present on completed
import jobs only. A non-zero
value does not mean the import failed.
type: integer
format: int64
example: 12
responses:
BadRequest:
description: Bad request. Please check error message and your parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: >-
Authorization failed. Please supply a valid `DeepL-Auth-Key` via the
`Authorization` header.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
ForbiddenScoped:
description: >-
Authorization failed. Please supply a valid `DeepL-Auth-Key` via the
`Authorization` header. This error is also returned when the API key is
scoped but does not include the scope required for this endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
TooManyRequests:
description: Too many requests. Please wait and resend your request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
InternalServerError:
description: Internal error.
ServiceUnavailable:
description: Resource currently unavailable. Try again later.
securitySchemes:
auth_header:
type: apiKey
description: >
Authentication with `Authorization` header and `DeepL-Auth-Key`
authentication scheme. Example: `DeepL-Auth-Key `
name: Authorization
in: header
x-default: 'DeepL-Auth-Key '
````