Job Status & Results¶

Monitor translation jobs, retrieve results, and manage job archives.

GET /v1/jobs¶

List all translation jobs for the authenticated account (paginated, newest first).

Authentication

Header: X-API-Key: your_api_key

Status: 200 OK

Query Parameters¶

Parameter	Type	Required	Default	Description
`limit`	`int`	no	`20`	Items per page (1--100).
`cursor`	`string`	no	`null`	Pagination cursor from previous response.
`status`	`string`	no	`null`	Filter by job status (e.g., `completed`, `processing`).
`project_name`	`string`	no	`null`	Filter by project name (exact match).

Response (200)¶

{
  "data": [
    {
      "job_id": "550e8400-e29b-41d4-a716-446655440000",
      "batch_id": null,
      "status": "completed",
      "mode": "translation",
      "source_lang": "de",
      "target_lang": "en",
      "quality": "standard",
      "project_name": "Website",
      "word_count": 150,
      "billed_words": 150,
      "qa_score": 96.5,
      "is_file_job": false,
      "archived": false,
      "created_at": "2026-03-20T10:00:00+00:00",
      "completed_at": "2026-03-20T10:00:12+00:00"
    }
  ],
  "pagination": {
    "cursor": "eyJ...",
    "has_more": true
  }
}

Note

Archived jobs are excluded by default. Use GET /v1/jobs/{job_id} to access archived jobs directly.

Examples¶

cURLPythonJavaScript

# List recent jobs
curl -X GET "https://app.falara.io/v1/jobs?limit=10" \
  -H "X-API-Key: $FALARA_API_KEY"

# Filter by project
curl -X GET "https://app.falara.io/v1/jobs?project_name=Website&status=completed" \
  -H "X-API-Key: $FALARA_API_KEY"

# Paginate
curl -X GET "https://app.falara.io/v1/jobs?cursor=eyJ..." \
  -H "X-API-Key: $FALARA_API_KEY"

import requests

# List recent jobs
response = requests.get(
    "https://app.falara.io/v1/jobs",
    headers={"X-API-Key": FALARA_API_KEY},
    params={"limit": 10},
)
jobs = response.json()

# Paginate through all jobs
all_jobs = []
cursor = None
while True:
    params = {"limit": 100}
    if cursor:
        params["cursor"] = cursor
    response = requests.get(
        "https://app.falara.io/v1/jobs",
        headers={"X-API-Key": FALARA_API_KEY},
        params=params,
    )
    page = response.json()
    all_jobs.extend(page["data"])
    if not page["pagination"]["has_more"]:
        break
    cursor = page["pagination"]["cursor"]

// List recent jobs
const response = await fetch(
  "https://app.falara.io/v1/jobs?limit=10",
  { headers: { "X-API-Key": FALARA_API_KEY } }
);
const jobs = await response.json();

// Filter by project and status
const filtered = await fetch(
  "https://app.falara.io/v1/jobs?project_name=Website&status=completed",
  { headers: { "X-API-Key": FALARA_API_KEY } }
);
console.log(await filtered.json());

Errors¶

Status	Description
`401`	Invalid or missing API key.
`422`	Invalid query parameters.

GET /v1/jobs/{job_id}¶

Get detailed status of a single job including segment breakdown.

Authentication

Header: X-API-Key: your_api_key

Status: 200 OK

Response (200)¶

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "batch_id": null,
  "status": "completed",
  "current_step": null,
  "mode": "translation",
  "source_lang": "de",
  "target_lang": "en",
  "quality": "standard",
  "project_name": "Website",
  "source_review_enabled": false,
  "word_count": 150,
  "billed_words": 150,
  "qa_score": 96.5,
  "cost_eur": 0.03,
  "token_usage": {
    "input": 1200,
    "output": 800
  },
  "segments": [
    {
      "id": 1,
      "status": "completed",
      "qa_score": 98.0,
      "retry_count": 0,
      "error": null
    }
  ],
  "created_at": "2026-03-20T10:00:00+00:00",
  "completed_at": "2026-03-20T10:00:12+00:00"
}

Status Values¶

Status	Description
`queued`	Job is waiting for a worker.
`processing`	Pipeline is running.
`completed`	All segments passed QA.
`completed_with_blocks`	Completed but some segments could not be reassembled (file jobs).
`needs_review`	QA score below threshold after correction loops.
`failed`	Unrecoverable error.
`dead`	Abandoned after repeated failures.

Current Step Values¶

Step	Description
`supervisor`	Validating and segmenting.
`source_review`	Checking source text quality.
`translator`	Translating segments.
`qa`	Quality evaluation.
`finalizing`	Building output.
`null`	Not currently processing.

Examples¶

cURLPythonJavaScript

curl -X GET "https://app.falara.io/v1/jobs/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: $FALARA_API_KEY"

import requests

response = requests.get(
    f"https://app.falara.io/v1/jobs/{job_id}",
    headers={"X-API-Key": FALARA_API_KEY},
)
job = response.json()
print(f"Status: {job['status']}, Step: {job['current_step']}")
print(f"QA Score: {job['qa_score']}, Segments: {len(job['segments'])}")

const response = await fetch(
  `https://app.falara.io/v1/jobs/${jobId}`,
  { headers: { "X-API-Key": FALARA_API_KEY } }
);
const job = await response.json();
console.log(`Status: ${job.status}, Step: ${job.current_step}`);

Errors¶

Status	Description
`401`	Invalid or missing API key.
`404`	Job not found.

GET /v1/jobs/{job_id}/result¶

Get the translation result. Only available when the job is in a terminal status (completed, completed_with_blocks, needs_review, failed, dead).

Authentication

Header: X-API-Key: your_api_key

Status: 200 OK

Response (200)¶

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "translation": "The quality of our products speaks for itself.",
  "qa_score": 96.5,
  "word_count": {
    "source": 8,
    "target": 9
  },
  "billed_words": 9,
  "delivery_notes": [],
  "warning": null
  "item_metadata": { "resource_id": "gid://shopify/Product/123" }
}

Batch Text Jobs

For jobs created with the texts input (list of strings), the translation field is a list of translated strings in the same order as the input.

Metadata Passthrough

Batch Content Metadata

For jobs created via POST /v1/jobs/batch-content, the item_metadata field contains the metadata object from the original request item. Use this to map results back to source records (e.g., Shopify product IDs). For jobs where texts contained objects with metadata, the translation field is an array of {"text": "...", "metadata": {...}} objects. See Text Translation — Metadata Passthrough for details.

Batch Content Metadata

For jobs created via POST /v1/jobs/batch-content, the item_metadata field contains the metadata object from the original request item. Use this to map results back to source records (e.g., Shopify product IDs).

Examples¶

cURLPythonJavaScript

curl -X GET "https://app.falara.io/v1/jobs/550e8400-.../result" \
  -H "X-API-Key: $FALARA_API_KEY"

import requests

response = requests.get(
    f"https://app.falara.io/v1/jobs/{job_id}/result",
    headers={"X-API-Key": FALARA_API_KEY},
)
result = response.json()
print(result["translation"])

const response = await fetch(
  `https://app.falara.io/v1/jobs/${jobId}/result`,
  { headers: { "X-API-Key": FALARA_API_KEY } }
);
const result = await response.json();
console.log(result.translation);

Errors¶

Status	Description
`401`	Invalid or missing API key.
`404`	Job not found.
`409`	Job not yet complete.

Job Archiving¶

Archive jobs to hide them from the list view without deleting them. Archived jobs remain accessible via GET /v1/jobs/{job_id}.

PATCH /v1/jobs/{job_id}/archive¶

Archive a single job.

Authentication

Header: X-API-Key: your_api_key

Status: 200 OK

cURLPythonJavaScript

curl -X PATCH "https://app.falara.io/v1/jobs/550e8400-.../archive" \
  -H "X-API-Key: $FALARA_API_KEY"

import requests

response = requests.patch(
    f"https://app.falara.io/v1/jobs/{job_id}/archive",
    headers={"X-API-Key": FALARA_API_KEY},
)
print(response.json())

await fetch(`https://app.falara.io/v1/jobs/${jobId}/archive`, {
  method: "PATCH",
  headers: { "X-API-Key": FALARA_API_KEY },
});

PATCH /v1/jobs/{job_id}/unarchive¶

Restore an archived job so it reappears in the list view.

Authentication

Header: X-API-Key: your_api_key

Status: 200 OK

cURLPythonJavaScript

curl -X PATCH "https://app.falara.io/v1/jobs/550e8400-.../unarchive" \
  -H "X-API-Key: $FALARA_API_KEY"

import requests

response = requests.patch(
    f"https://app.falara.io/v1/jobs/{job_id}/unarchive",
    headers={"X-API-Key": FALARA_API_KEY},
)
print(response.json())

await fetch(`https://app.falara.io/v1/jobs/${jobId}/unarchive`, {
  method: "PATCH",
  headers: { "X-API-Key": FALARA_API_KEY },
});

POST /v1/jobs/archive-all¶

Archive all visible (non-archived) jobs at once.

Authentication

Header: X-API-Key: your_api_key

Status: 200 OK

Response¶

{
  "archived_count": 42
}

cURLPythonJavaScript

curl -X POST https://app.falara.io/v1/jobs/archive-all \
  -H "X-API-Key: $FALARA_API_KEY"

import requests

response = requests.post(
    "https://app.falara.io/v1/jobs/archive-all",
    headers={"X-API-Key": FALARA_API_KEY},
)
print(f"Archived {response.json()['archived_count']} jobs")

const response = await fetch("https://app.falara.io/v1/jobs/archive-all", {
  method: "POST",
  headers: { "X-API-Key": FALARA_API_KEY },
});
const data = await response.json();
console.log(`Archived ${data.archived_count} jobs`);

POST /v1/jobs/archive-batch¶

Archive specific jobs by ID.

Authentication

Header: X-API-Key: your_api_key

Content-Type: application/json Status: 200 OK

Request Body¶

{
  "job_ids": [
    "550e8400-e29b-41d4-a716-446655440001",
    "550e8400-e29b-41d4-a716-446655440002"
  ]
}

Response¶

{
  "archived_count": 2
}

cURLPythonJavaScript

curl -X POST https://app.falara.io/v1/jobs/archive-batch \
  -H "X-API-Key: $FALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_ids": [
      "550e8400-e29b-41d4-a716-446655440001",
      "550e8400-e29b-41d4-a716-446655440002"
    ]
  }'

import requests

response = requests.post(
    "https://app.falara.io/v1/jobs/archive-batch",
    headers={"X-API-Key": FALARA_API_KEY},
    json={
        "job_ids": [
            "550e8400-e29b-41d4-a716-446655440001",
            "550e8400-e29b-41d4-a716-446655440002",
        ]
    },
)
print(f"Archived {response.json()['archived_count']} jobs")

const response = await fetch("https://app.falara.io/v1/jobs/archive-batch", {
  method: "POST",
  headers: {
    "X-API-Key": FALARA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    job_ids: [
      "550e8400-e29b-41d4-a716-446655440001",
      "550e8400-e29b-41d4-a716-446655440002",
    ],
  }),
});
const data = await response.json();
console.log(`Archived ${data.archived_count} jobs`);