guides
Tracking long-running operations
Many calls start work that goes on after they answer: ingesting a project's files, building an export kit, importing a bilingual file, running a logfile. Each of these operations has its own status call, with the details that belong to it. Get Operation Status reports any of them in the same terms, so an integration can poll them all the same way.
Polling one call for every operation
Call GET /api/v3/operations/{type}/{id} with the operation's type and the id the starting call returned. Some types also need the project (projectUuid) or the work unit (workUnitUuid) as query parameters, see the table below.
{
"type": "TRANSLATION_KIT_JOB",
"id": "7c2e4b1a-9f3d-4e8a-b6c5-1d2f3a4b5c6d",
"state": "COMPLETED",
"statusUrl": "/api/v3/project/0b8f6c2e-3a4d-4f5b-8c7d-9e1f2a3b4c5d/translation-kit-job/7c2e4b1a-9f3d-4e8a-b6c5-1d2f3a4b5c6d"
}
stateisRUNNINGuntil the operation ends, thenCOMPLETEDorFAILED. OnlyPROJECT_INGESTIONcan beRUNNINGagain, when more files are added to the project.statusUrlis the operation's own status call. Call it once the state is final for what the operation produced: a download link, the counts of an import, the reason of a failure.- You need the permission of the operation's own status call, and access to its project or translation memory. A caller without it gets
403. - An unknown
type, an id of the wrong form, or a missingprojectUuidorworkUnitUuidanswers400. An operation that does not exist, has expired, or belongs to another project answers404.
There is no list of running operations: keep the ids the starting calls return. Where a webhook exists, prefer it to polling, and poll only as a fallback.
Operation types
type | Started by | id | Also needs | Own status call | Native states, then final | Webhook when it ends |
|---|---|---|---|---|---|---|
PROJECT_INGESTION | Adding files to a project: Create Project Resource and Upload Project Resource Content, or Extract ZIP Resource | the project | Get Project Ingestion Status | IN_PROGRESS, then COMPLETED or COMPLETED_WARN (both COMPLETED) | PROJECT_INGESTION_COMPLETED | |
PROJECT_TRANSLATIONS_DOWNLOAD | Download Project Translations Async | the request | projectUuid | Download Project Translations Async Status | STARTED, then COMPLETED or FAILED | none |
ZIP_EXTRACTION | Extract ZIP Resource | the task | projectUuid | Get ZIP Extraction Status | IN_PROGRESS, then COMPLETED, or ERROR or CANCELLED (both FAILED) | none |
LOGFILE | Create Logfile | the logfile | projectUuid | Project Logfile Details | STARTING or STARTED, then COMPLETED or FAILED (STOPPED and ABANDONED are FAILED too) | PROJECT_LOGFILE_COMPLETED |
TRANSLATION_KIT_JOB | Request Export Project, Request Project Translated Files, Bulk Source Files, Bulk Import Kit | the job | projectUuid | Check Translation Kit Job Status | STARTING, then COMPLETED or FAILED | TRANSLATION_KIT_JOB_FINISHED |
WORK_UNIT_IMPORT | Import File to Work Unit, Import Kit to Work Unit | the import | projectUuid, workUnitUuid | Get Work Unit Import | STARTED, then IMPORTED (COMPLETED) or ERROR (FAILED) | WORK_UNIT_IMPORT_FINISHED |
WORK_UNIT_TM_UPDATE | Export Work Unit TM Updates | the job | projectUuid, workUnitUuid | Get Work Unit TM Update | SCHEDULED, STARTING or STARTED, then COMPLETED or FAILED | none |
TM_JOB | Import TM File, Export TM | the job | Get TM Job | SCHEDULED, STARTING or STARTED, then COMPLETED or FAILED (INTERRUPTED, STOPPED and ABANDONED are FAILED too) | none |
A project with no ingestion status never had files to ingest, so PROJECT_INGESTION reports it COMPLETED.
Some states are kept only for a while: a ZIP extraction for 10 minutes after its last change, a work unit TM update job for 24 hours. After that the operation answers 404.
What is not tracked here
Pre-translation, clearing translations, copying the source to the target and updating a source file have no public status call, so they have no type here. Neither do logfile and glossary exports, glossary imports, project routing and payables imports: follow their own status calls.