Create a batch job

POST/lang2fhir/batch

Opens an empty batch job. Items arrive on later upload calls and the set is sealed at finalize.

Supplying request_id makes the create idempotent on that token: a retried submit whose response was lost returns the original job rather than opening a second one. This dedupe is scoped to the calling credential.

An instance may hold at most 4 active (pending or processing) jobs at once; a create past that limit returns 409. The limit is instance-wide — jobs are shared across the instance's credentials — so another credential's jobs count against it.

RequiresBearerauthentication

Body parameters

request_idstringoptional

Optional client idempotency token. A retried create with the same token returns the original job instead of opening a second one.

Returns

Batch job created (or an idempotent replay of an existing job)

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.

pendingprocessingcompletedfailed

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 or failed. 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" \
  -H "Authorization: Bearer $PHENOML_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "request_id": "submit-2025-09-02-batch-001"
}'

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"
}