Finalize a batch job

POST/lang2fhir/batch/{job_id}/finalize

Seals the job's item set and starts processing. Takes no request body. Finalize is idempotent: a retried finalize succeeds again.

If a previous upload did not complete, finalize returns a 409; re-send the missing upload (with the same request_id), then finalize. Finalizing a job with no items is a 400.

RequiresBearerauthentication

Path parameters

job_idstringrequired

Returns

Job finalized and processing started

Response fields

job_idstringrequired

Server-assigned job identifier.

request_idstringoptional

The idempotency token supplied at create, if any.

statusstringrequired

Job status. completed means every item has finished — some may have failed, so check counts for the split. failed is a whole-job failure (the job could not run at all), distinct from individual item failures, which never fail the job. canceled is a caller-requested cancellation via POST /lang2fhir/batch/{job_id}/cancel; like the other terminal states it keeps any results already produced readable for the retention window.

pendingprocessingcompletedfailedcanceled

finalizedbooleanrequired

Whether the job's item set has been sealed.

total_itemsintegerrequired

The sealed item count. It is 0 until the job is finalized, so an upload response always reports 0; poll the job after finalize for the real count.

errorobjectoptional

A whole-job failure. Present only on a failed job.

created_atstring (date-time)required

updated_atstring (date-time)required

completed_atstring (date-time)optional

When the job finished. Absent until then.

expires_atstring (date-time)required

When the job and its stored inputs and results are deleted. Set 7 days out, with the clock restarting when the job reaches completed, failed, or canceled. At expiry the job's request_id is freed for reuse.

POSTRequest

# Get authentication token
PHENOML_TOKEN=$(curl -X POST "https://experiment.app.pheno.ml/v2/auth/token" \
  -u "$PHENOML_CLIENT_ID:$PHENOML_CLIENT_SECRET" \
  | jq -r '.access_token')

curl -X POST "https://experiment.app.pheno.ml/lang2fhir/batch/abc-123-def-456/finalize" \
  -H "Authorization: Bearer $PHENOML_TOKEN"

202 AcceptedExample Response

{
  "job_id": "l2f_batch_6f1d2c3a-8b4e-4f5a-9c7d-0e1f2a3b4c5d",
  "request_id": "submit-2025-09-02-batch-001",
  "status": "pending",
  "finalized": false,
  "total_items": 12,
  "error": {
    "kind": "processing_failed",
    "message": "the item could not be converted"
  },
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "completed_at": "2024-01-15T09:30:00Z",
  "expires_at": "2024-01-15T09:30:00Z"
}