Workflows

Workflows in a project: multi-step automations, configured in the Lokalise UI, that translate and review the keys changed since their last run.

Workflows are multi-step automations you configure in the Lokalise workflow editor: AI translation, translation memory, human translation and review tasks. With the Workflows API, your pipeline can start a workflow right after it uploads new content, instead of waiting for the workflow's schedule, and know when the run has finished so it can download the result.

The API covers running workflows, not configuring them. You create and edit workflows in the Lokalise UI, then use the API to:

  • list the workflows in a project, to find the one to start;
  • start a run of a workflow;
  • follow a run: its status, the step it's on, and the tasks each step created;
  • list past and current runs.

Before you start

You need:

  • Workflows on your plan, and access to the Lokalise API (the same rules as the rest of the API).
  • A read-write API token of a user who is a contributor on the project with the Manage project settings permission. Every Workflows API endpoint requires this permission, reads included, as the workflow editor does. A read-only token can list workflows and follow runs, but starting a run returns 403.

Send the token in the X-Api-Token header, as with the rest of the Lokalise API.

This API is not API2

The Workflows endpoints live under https://api.lokalise.com/v1/, not /api2/, and follow Lokalise's newer API conventions:

API2 (/api2/…)Workflows API (/v1/…)
Field namessnake_casecamelCase
Filtersfilter_…filter-… (kebab-case), comma-separated values
Paginationpage numbers, X-Pagination-* headerscursor: limit + after, with meta.cursor and meta.hasMore in the body
Enveloperesource name as the key{ "data": …, "meta": … }
Errors{ "error": { "message", "code" } }{ "message", "errorCode", "details" }

The recipe below uses both: API2 for files and tasks, the Workflows API for runs.

Identifiers

Every Workflows API path starts with /v1/teams/{teamId}/projects/{projectId}.

ParameterFormatWhere to get it
teamIdNumeric, for example 123456team_id in Retrieve a project or List all teams. The team must own the project.
projectId<hex>.<digits>, for example 98616399660d3c2456abc5.66984240project_id in API2. The project uuid isn't accepted: a request with it returns 404.
workflowIduuidList workflows
runIduuidThe response to Start a run, or List runs
Language idsstrings, for example "640"lang_id in List project languages
Task idsstrings, for example "1834221"Returned on each run step. Use them with Retrieve a task.

All ids in Workflows API responses are strings, including numeric ones.

Set up a workflow for the API

  1. In the project, open Workflows and create a workflow, or open an existing one.
  2. In the trigger step, set Trigger to On demand if the workflow should only run when you start it (triggerType: manual in the API). A Scheduled workflow can also be started through the API, or with Run workflow in the UI, and keeps running on its schedule.
  3. Configure the trigger's scope (source language, target languages, key filters) and the steps, then activate the workflow. Only live workflows can be started.

We recommend one on-demand workflow per pipeline that starts it. A run picks up every matching change in the project since the workflow's previous run, so a workflow shared by several pipelines, or that is also run by hand, will process their content too. See What a run processes.

End-to-end recipe

The usual loop: upload content, wait for Lokalise to process it, start the workflow, check the run until it ends, then download the translations.

upload file ─► wait for upload process ─► start run ─► check run ─► download
   (API2)            (API2)                (v1)          (v1)         (API2)

1. Upload your content and wait for it to be processed

Upload a file. The upload is processed in the background, and the response returns a process to follow:

curl -X POST "https://api.lokalise.com/api2/projects/$PROJECT_ID/files/upload" \
  -H "X-Api-Token: $LOKALISE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filename": "en.json", "lang_iso": "en", "data": "<base64>"}'

Check Retrieve a process until its status is finished:

curl "https://api.lokalise.com/api2/projects/$PROJECT_ID/processes/$PROCESS_ID" \
  -H "X-Api-Token: $LOKALISE_TOKEN"
🚧

Don't start the workflow before the upload has finished

Keys that change after a run starts are not lost, but they go into the next run, not this one.

2. Find the workflow

You only need to do this once: store the workflow id in your configuration.

curl "https://api.lokalise.com/v1/teams/$TEAM_ID/projects/$PROJECT_ID/workflows?filter-statuses=live&filter-trigger-types=manual" \
  -H "X-Api-Token: $LOKALISE_TOKEN"
{
  "data": [
    {
      "id": "6f1c2b8e-4d0a-4b7e-9f3a-1c2d3e4f5a6b",
      "name": "API: AI translate + review",
      "status": "live",
      "triggerType": "manual",
      "lastTriggeredAt": "2026-11-10T14:02:11.000Z",
      "nextManualRunAvailableAt": null,
      "createdAt": "2026-11-01T09:30:00.000Z",
      "updatedAt": "2026-11-05T11:12:13.000Z"
    }
  ],
  "meta": { "count": 1, "hasMore": false }
}

nextManualRunAvailableAt tells you when the workflow can next be started (see Cooldown). null means the cooldown doesn't hold it back.

3. Start a run

curl -X POST "https://api.lokalise.com/v1/teams/$TEAM_ID/projects/$PROJECT_ID/workflows/$WORKFLOW_ID/actions/run" \
  -H "X-Api-Token: $LOKALISE_TOKEN"

The request has no body. This is the same as Run workflow in the Lokalise UI. The run continues in the background, so the response is 202 Accepted, with the run and the URL to follow it:

{
  "data": {
    "id": "b2e9a1d4-7c3f-4e8a-a0b1-9d8c7e6f5a4b",
    "workflowId": "6f1c2b8e-4d0a-4b7e-9f3a-1c2d3e4f5a6b",
    "status": "in_progress",
    "type": "manual",
    "createdAt": "2026-11-11T10:00:00.000Z"
  },
  "meta": {
    "statusUrl": "https://api.lokalise.com/v1/teams/123456/projects/98616399660d3c2456abc5.66984240/workflow-runs/b2e9a1d4-7c3f-4e8a-a0b1-9d8c7e6f5a4b"
  }
}

Store data.id. If you call too early, you get 429 (see Cooldown).

4. Check the run until it ends

GET the meta.statusUrl every 30 to 60 seconds until data.status is completed or failed:

curl "$STATUS_URL" -H "X-Api-Token: $LOKALISE_TOKEN"
{
  "data": {
    "id": "b2e9a1d4-7c3f-4e8a-a0b1-9d8c7e6f5a4b",
    "workflowId": "6f1c2b8e-4d0a-4b7e-9f3a-1c2d3e4f5a6b",
    "workflowName": "API: AI translate + review",
    "status": "in_progress",
    "type": "manual",
    "createdAt": "2026-11-11T10:00:00.000Z",
    "completedAt": null,
    "targetLanguageIds": ["640", "673"],
    "keysAffectedCount": 412,
    "currentStep": { "id": "review_1", "type": "review_task_step", "title": "Human review" },
    "steps": [
      { "id": "trigger", "type": "trigger_step", "title": "Start", "status": "completed", "tasks": [] },
      { "id": "ai_1", "type": "ai_mt_translation_step", "title": "AI translate", "status": "completed", "tasks": [{ "id": "1834221" }] },
      { "id": "review_1", "type": "review_task_step", "title": "Human review", "status": "in_progress", "tasks": [{ "id": "1834230" }, { "id": "1834231" }] }
    ],
    "error": null
  },
  "meta": {
    "links": { "tasks": "https://api.lokalise.com/api2/projects/98616399660d3c2456abc5.66984240/tasks" }
  }
}

See Reading a run for what each field means, and Check a run's status for how often to check a long run.

5. Download the translations

When the run is completed, download the files as usual (use the asynchronous download for large projects).

If the run is failed, read data.error (see When a run fails).

Example: the whole loop

const BASE = `https://api.lokalise.com/v1/teams/${teamId}/projects/${projectId}`
const headers = { 'X-Api-Token': process.env.LOKALISE_TOKEN! }
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))

async function runWorkflow(workflowId: string) {
  let res = await fetch(`${BASE}/workflows/${workflowId}/actions/run`, { method: 'POST', headers })

  if (res.status === 429) {
    const retryAfterSeconds = Number(res.headers.get('retry-after') ?? 60)
    await sleep(retryAfterSeconds * 1000)
    res = await fetch(`${BASE}/workflows/${workflowId}/actions/run`, { method: 'POST', headers })
  }
  if (res.status !== 202) throw new Error(`Could not start the run: ${res.status} ${await res.text()}`)

  const { meta } = await res.json()

  while (true) {
    await sleep(60_000)
    const { data: run } = await (await fetch(meta.statusUrl, { headers })).json()
    if (run.status === 'completed') return run
    if (run.status === 'failed') throw new Error(`Run failed (${run.error?.type}): ${run.error?.message}`)
  }
}

What a run processes

A run doesn't take a list of keys. It processes every key that changed since the workflow's previous run collected its keys and that matches the scope set in its trigger step (source language, target languages, key filters).

  • The previous run can be any run of the workflow: started through the API, with Run workflow in the UI, or by its schedule.
  • The first run of a new workflow processes the changes since the workflow was created.
  • Changes made by anyone count, not only your uploads: edits in the editor, other integrations, other pipelines.
  • Keys that change while a run is in progress go into the next run.
  • keysAffectedCount on the run is the number of keys it processes, once that's known.
  • If nothing changed, the run completes right away with keysAffectedCount: 0.

So: wait for your upload to finish processing before starting the run, and give each pipeline its own workflow.

Cooldown between runs

Runs of the same workflow must start at least 15 minutes apart. The cooldown counts from the workflow's last run of any kind, so a scheduled run or a Run workflow in the UI also starts it.

Starting a run during the cooldown returns 429 Too Many Requests with a Retry-After header, in seconds, and the time the workflow can next be started:

HTTP/1.1 429 Too Many Requests
Retry-After: 542
Content-Type: application/json

{
  "message": "The action is rate limited per Workflow",
  "errorCode": "TOO_MANY_REQUESTS",
  "details": {
    "workflowId": "6f1c2b8e-4d0a-4b7e-9f3a-1c2d3e4f5a6b",
    "cooldown": 900,
    "cooldownUnit": "Seconds",
    "nextManualRunAvailableAt": "2026-11-11T10:15:00.000Z"
  }
}

Wait Retry-After seconds, then try again. You can also read nextManualRunAvailableAt from Get a workflow before starting.

The cooldown makes each run process a meaningful batch of changes rather than many small ones, and means runs of the same workflow overlap less. It's a product rule per workflow, separate from the API's request rate limits.

Check a run's status

Get the run at meta.statusUrl (the Get a run endpoint) to see its status, the step it's on and the tasks it created.

  • Check the run every 30 to 60 seconds.
  • Stop once status is completed or failed. Those are final.
  • Runs with human translation or review steps can take hours or days, until the assignees close their tasks. Once currentStep.type is a human step (translate_task_step, review_task_step, review_task_ai_scoring_step), check less often, for example every 5 to 15 minutes.
  • To follow several runs, use List runs with filter-statuses=in_progress instead of getting each one.
  • The standard Lokalise API rate limits apply.

Reading a run

FieldMeaning
statusin_progress until the run ends, then completed or failed.
typemanual (started through the API or Run workflow) or scheduled.
createdAt, completedAtWhen the run started and ended. completedAt is null while it's in progress.
workflowNameThe workflow's name as it is now.
targetLanguageIdsThe languages the run translates into, as the workflow was set up when the run started.
keysAffectedCountThe number of keys the run processes, or null until that's known.
currentStepThe step the run is on, or the step it failed on. null once the run has completed.
stepsThe steps the run has entered, in order, ending with the current one. Steps the run hasn't reached aren't listed, so this list grows as the run progresses.
steps[].statuscompleted once the run has moved past the step, otherwise the run's status.
steps[].tasksThe Lokalise tasks the step created, oldest first, for example one per target language. Empty for steps that create no tasks (AI translation, translation memory).
errorWhy the run failed, or null.

Each task id works with the API2 tasks endpoints, for example Retrieve a task, to see its assignees and progress. meta.links.tasks points at the project's task list.

When a run fails

A failed run has an error with a type and a message:

error.typeMeaningWhat happens to the workflow
configurationThe workflow's settings stop it from running, for example a language or filter it refers to was removed.The workflow is canceled. Fix it in the workflow editor and activate it again.
entitlementThe team lost access to a feature the workflow uses.The workflow is canceled.
systemAn error on our side.The workflow stays live. Start a new run; if it keeps failing, contact support with the run id.

Runs that failed before late October 2026 have error: null.

What happens to the keys of a failed run depends on when it failed:

  • Before it collected its keys (keysAffectedCount is null): nothing is lost. The next run picks up those changes.
  • After it collected its keys: the next run doesn't include them. They're processed again only if they change again.

Overlapping runs

A workflow can have several runs in progress at once: starting a run doesn't wait for the previous one. This is normal for workflows with human steps, which can take days.

If your pipeline needs one run at a time, check before starting:

curl "https://api.lokalise.com/v1/teams/$TEAM_ID/projects/$PROJECT_ID/workflow-runs?filter-workflow-ids=$WORKFLOW_ID&filter-statuses=in_progress&limit=1" \
  -H "X-Api-Token: $LOKALISE_TOKEN"

List runs

GET /v1/teams/{teamId}/projects/{projectId}/workflow-runs lists the runs of a project, newest first. List items have the same fields as a run, without steps; get the run to see its steps and tasks.

Query parameterDescription
filter-workflow-idsOnly runs of these workflows.
filter-statusesin_progress, completed, failed.
filter-target-language-idsOnly runs that translate into at least one of these languages.
filter-created-after, filter-created-beforeISO 8601 date-times. Without them, the list covers the last 90 days.
limit1 to 100, default 10.
afterThe meta.cursor of the previous page.

Pass several values as a comma-separated list, for example filter-statuses=in_progress,failed.

Pagination

Both list endpoints use cursor pagination. Read the next page by passing the previous response's meta.cursor as after, while meta.hasMore is true:

"meta": { "count": 10, "cursor": "b2e9a1d4-7c3f-4e8a-a0b1-9d8c7e6f5a4b", "hasMore": true }

Errors

Errors have the body { "message", "errorCode", "details" }.

StatuserrorCodeWhen
400VALIDATION_ERRORA malformed id (for example a project uuid sent straight to the service), an unknown filter value, or filter-created-after not before filter-created-before.
401Missing or invalid token.
403ACCESS_DENIEDThe token's user isn't a contributor with the Manage project settings permission on the project; the project isn't in the token's team; or the token is read-only (on start).
403ACCESS_VIOLATIONStarting a run: the team no longer has access to Workflows or to a feature the workflow uses. details.violation says which. The workflow is canceled, the same as when this happens on a scheduled run.
404WORKFLOW_NOT_FOUND, WORKFLOW_RUN_NOT_FOUNDNo such workflow or run in this project. A project uuid instead of the project id also returns 404.
409WORKFLOW_NOT_LIVEStarting a run of a workflow that isn't live. details.status has its status.
429TOO_MANY_REQUESTSThe cooldown hasn't elapsed. Honour Retry-After.

A 401, or a 404 for a path the API doesn't serve (such as one with a project uuid), can come from the API gateway, without this body. Rely on the status code for those.

What the API doesn't cover

  • Creating, editing, activating, pausing or deleting workflows. Use the workflow editor.
  • Canceling a run.
  • Notifications when a run completes or fails. Use Get a run to check its status.
  • Starting a run on a specific set of keys, tags or files. A run always processes the changes since the previous run.
  • Vantage (Lokalise NextGen) projects.