Job Status & Results

GET /v1/jobs/{job_id}

Get the current status and segment breakdown of a job.

Auth: X-API-Key required

Response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "segment_count": 5,
  "segments": [
    { "id": 0, "status": "translated", "qa_score": 92.5, "retry_count": 0, "error": null },
    { "id": 1, "status": "pending", "qa_score": null, "retry_count": 0, "error": null }
  ],
  "token_usage": { "input_tokens": 1200, "output_tokens": 800 },
  "cost_eur": 0.0014,
  "error_log": [],
  "created_at": "2026-03-06T10:00:00+00:00",
  "started_at": "2026-03-06T10:00:05+00:00",
  "finished_at": null,
  "current_step": "translator",
  "source_review_enabled": false
}

---

Job Status Values

Status	Description
queued	Job is waiting to be picked up by a worker
processing	Pipeline is actively running
correcting	QA found issues; correction loop in progress
completed	All segments translated and QA passed
completed_with_blocks	Translation complete but some segments were blocked (markup issues)
needs_review	QA score below minimum threshold after max correction loops
failed	Job failed due to a recoverable error
dead	Job permanently failed after all retries exhausted

---

current_step Values

Indicates which pipeline stage is currently active. null when the job is idle (queued or finished).

Value	Stage
supervisor	Briefing validation and segmentation
source_review	Source text quality check (optional)
translator	Segment-by-segment translation
qa	Quality assessment
finalizing	Assembling the final output
null	Job is queued or has finished

---

Segment Status Values

Status	Description
pending	Not yet processed
processing	Currently being translated
translated	Translation complete, awaiting QA
qa_passed	QA score meets threshold
qa_failed	QA score below threshold, may trigger correction
blocked	Segment could not be translated (markup conflict, etc.)
correcting	Correction loop in progress
done	Finalized (QA passed or correction accepted)
failed	Segment permanently failed

---

Error Codes

Code	Description
401	Missing or invalid X-API-Key
404	Job not found

---

GET /v1/jobs/{job_id}/result

Retrieve the completed translation result.

Auth: X-API-Key required Available when: status is completed, completed_with_blocks, or needs_review

Response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "translation": "The quality of our products speaks for itself.",
  "segments": [
    {
      "id": 0,
      "source": "Die Qualität unserer Produkte spricht für sich.",
      "translation": "The quality of our products speaks for itself.",
      "qa_score": 96.5,
      "status": "done"
    }
  ],
  "cost_eur": 0.0014,
  "token_usage": {
    "input": 1200,
    "output": 800,
    "cache_read": 400,
    "cache_write": 0,
    "total": 2000
  },
  "word_count": { "source": 8, "target": 9 },
  "qa_score": 96.5,
  "warning": null,
  "delivery_notes": []
}

Response Fields

Field	Type	Description
translation	string	Full assembled translation (markup placeholders removed)
qa_score	float	Average QA score across all segments (0–100)
warning	string | null	Set when status is needs_review
delivery_notes	list	Structured notes from agents on quality issues
word_count	object	{ source: int, target: int }

Delivery Note Types

Type	Description
source_error	Source text quality issue detected by Source Review
low_confidence	Agent flagged low confidence in the translation
length_deviation	Target text significantly shorter or longer than source
terminology	Glossary term could not be applied as specified

Error Codes

Code	Description
401	Missing or invalid X-API-Key
404	Job not found
409	Job not yet complete; body includes current status