Batch Operations¶

POST /v1/jobs/batch-file¶

Submit multiple files for translation in a single request. Optionally translate each file into multiple target languages.

Auth: X-API-Key required Content-Type: multipart/form-data Status: 202 Accepted

Limits¶

Limit	Value
Max files per batch	20
Max total size	50 MB
Max target languages	10
Max total jobs (files × languages)	100

Form Fields¶

Field	Type	Required	Description
`files`	file[]	yes	1–20 files to translate
`briefing_json`	string (JSON)	yes	Translation settings. `target_lang` can be a string or list.

Response¶

{
  "batch_id": "b1c2d3e4-f5a6-7890-b1c2-d3e4f5a67890",
  "jobs": [
    {
      "job_id": "550e8400-e29b-41d4-a716-446655440000",
      "filename": "brochure.docx",
      "status": "queued",
      "target_language": "en",
      "word_count": 350,
      "estimated_cost_eur": 0.07,
      "error": null
    },
    {
      "job_id": "661f9511-f3ac-52e5-b827-557766551111",
      "filename": "brochure.docx",
      "status": "queued",
      "target_language": "fr",
      "word_count": 350,
      "estimated_cost_eur": 0.07,
      "error": null
    }
  ],
  "total_files": 1,
  "total_words": 700,
  "estimated_total_cost_eur": 0.14
}

Partial failures

If a single file fails to extract, it appears in the response with status: "error" and an error message. The rest of the batch continues processing normally.

Error Codes¶

Code	Description
`400`	Invalid `briefing_json`
`401`	Missing or invalid `X-API-Key`
`422`	No files submitted, too many files, invalid language combination, or total size exceeded

Example¶

cURLPython

curl -X POST https://falara.io/v1/jobs/batch-file \
  -H "X-API-Key: sk_live_..." \
  -F "files=@brochure.docx" \
  -F "files=@catalog.xlsx" \
  -F 'briefing_json={"mode":"translation","source_lang":"de","target_lang":["en","fr"]}'

import json, requests

files = [
    ("files", ("brochure.docx", open("brochure.docx", "rb"))),
    ("files", ("catalog.xlsx", open("catalog.xlsx", "rb"))),
]

r = requests.post(
    "https://falara.io/v1/jobs/batch-file",
    headers={"X-API-Key": "sk_live_..."},
    files=files,
    data={
        "briefing_json": json.dumps({
            "mode": "translation",
            "source_lang": "de",
            "target_lang": ["en", "fr"],
        })
    },
)
data = r.json()
batch_id = data["batch_id"]

GET /v1/jobs/batch/{batch_id}¶

Get the aggregated status of all jobs in a batch.

Auth: X-API-Key required

Response¶

{
  "batch_id": "b1c2d3e4-f5a6-7890-b1c2-d3e4f5a67890",
  "status": "processing",
  "source_language": "de",
  "target_languages": ["en", "fr"],
  "jobs": [
    {
      "job_id": "550e8400-...",
      "filename": "brochure.docx",
      "status": "completed",
      "target_language": "en",
      "qa_score": 94.5
    }
  ],
  "completed": 1,
  "total": 4,
  "total_cost_eur": 0.07
}

Batch Status Values¶

Status	Meaning
`processing`	At least one job is still running
`completed`	All jobs reached `completed` or `completed_with_blocks`
`partial`	All jobs terminal, but at least one `failed` or `needs_review`

Error Codes¶

401, 404 (batch not found)

GET /v1/jobs/batch/{batch_id}/download¶

Download all completed translations as a ZIP archive.

Auth: X-API-Key required

Query Parameters¶

Parameter	Type	Default	Description
`structure`	`"folders"` \| `"suffix"`	`"folders"`	ZIP layout for multi-language batches

ZIP Layout¶

folders (default):

batch_b1c2d3e4.zip
├── manifest.json
├── en/
│   ├── translated_brochure.docx
│   └── translated_catalog.xlsx
└── fr/
    ├── translated_brochure.docx
    └── translated_catalog.xlsx

suffix:

batch_b1c2d3e4.zip
├── manifest.json
├── translated_brochure_en.docx
├── translated_brochure_fr.docx
├── translated_catalog_en.xlsx
└── translated_catalog_fr.xlsx

manifest.json¶

Every ZIP includes a manifest with job metadata:

{
  "batch_id": "b1c2d3e4-f5a6-7890-b1c2-d3e4f5a67890",
  "created_at": "2026-03-06T10:00:00+00:00",
  "source_language": "de",
  "target_languages": ["en", "fr"],
  "structure": "folders",
  "files": [
    {
      "filename": "en/translated_brochure.docx",
      "target_language": "en",
      "status": "completed",
      "qa_score": 94.5,
      "words": 350
    }
  ],
  "skipped": [
    {
      "filename": "broken.pdf",
      "status": "failed",
      "error": "Unsupported file format"
    }
  ]
}

Response¶

StreamingResponse, Content-Type: application/zip Content-Disposition: attachment; filename=batch_b1c2d3e4.zip

Error Codes¶

401, 404 (batch not found or no completed jobs available for download)