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"
}

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

typeStarted byidAlso needsOwn status callNative states, then finalWebhook when it ends
PROJECT_INGESTIONAdding files to a project: Create Project Resource and Upload Project Resource Content, or Extract ZIP Resourcethe projectGet Project Ingestion StatusIN_PROGRESS, then COMPLETED or COMPLETED_WARN (both COMPLETED)PROJECT_INGESTION_COMPLETED
PROJECT_TRANSLATIONS_DOWNLOADDownload Project Translations Asyncthe requestprojectUuidDownload Project Translations Async StatusSTARTED, then COMPLETED or FAILEDnone
ZIP_EXTRACTIONExtract ZIP Resourcethe taskprojectUuidGet ZIP Extraction StatusIN_PROGRESS, then COMPLETED, or ERROR or CANCELLED (both FAILED)none
LOGFILECreate Logfilethe logfileprojectUuidProject Logfile DetailsSTARTING or STARTED, then COMPLETED or FAILED (STOPPED and ABANDONED are FAILED too)PROJECT_LOGFILE_COMPLETED
TRANSLATION_KIT_JOBRequest Export Project, Request Project Translated Files, Bulk Source Files, Bulk Import Kitthe jobprojectUuidCheck Translation Kit Job StatusSTARTING, then COMPLETED or FAILEDTRANSLATION_KIT_JOB_FINISHED
WORK_UNIT_IMPORTImport File to Work Unit, Import Kit to Work Unitthe importprojectUuid, workUnitUuidGet Work Unit ImportSTARTED, then IMPORTED (COMPLETED) or ERROR (FAILED)WORK_UNIT_IMPORT_FINISHED
WORK_UNIT_TM_UPDATEExport Work Unit TM Updatesthe jobprojectUuid, workUnitUuidGet Work Unit TM UpdateSCHEDULED, STARTING or STARTED, then COMPLETED or FAILEDnone
TM_JOBImport TM File, Export TMthe jobGet TM JobSCHEDULED, 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.