Analysis jobs¶

A job is one analysis run on one image. You submit it, and PoreStore runs it on hardware suited to it. When it completes, its result is stored and can be read any number of times. You can cancel a job until it starts running. PoreStore cancels one itself when it waits or runs far past its limits.

A diffusivity or conductivity job cancelled at its time limit while processing completes if its result arrives later.

Submit a job¶

POST /api/v1/teams/{team_id}/analysis-jobs/

Optional header: Idempotency-Key. See below.

curl --fail-with-body -sS -X POST "$PORESTORE_HOST/api/v1/teams/$PORESTORE_TEAM_ID/analysis-jobs/" \
  -H "Authorization: Api-Key $PORESTORE_API_KEY" \
  -H "Idempotency-Key: porosity-campaign-sample-17" \
  -H 'Content-Type: application/json' \
  --data '{
    "image_id": "9d2b6f0e-1c3a-4e5b-8f7d-2a4c6e8b0d1f",
    "analysis_type": "diffusivity",
    "parameters": {
      "direction": "z",
      "target_relative_error": 0.001,
      "solver_tolerance": 0.00001,
      "queue_name": "tortuosity-jl",
      "compute_tier": "auto"
    }
  }'

Response 202: the new job.

Response 200 with header Idempotency-Replayed: true: a replay of a job you already submitted with this key.

Errors

Idempotency¶

A network timeout leaves you with a real question: did the job get created? Send an Idempotency-Key header (any string up to 255 characters, unique per intended job) and you can retry safely:

• Same key, same request: you get the original job back, 200 with Idempotency-Replayed: true. Nothing is dispatched again.
• Same key, different request: 409 idempotency_conflict. "Different" is judged after parameters are normalised, so sending a default explicitly or leaving it out counts as the same request.
• New key: a new job.

Keys are scoped to the team, so any authorised member's retry with the same key finds the same job. A UUID per job works well, and so does a deterministic name such as campaign-7/sample-17/permeability-x if you want reruns of a script to be no-ops.

Without a key, don't blindly retry a timed-out submission. List the team's jobs first and look for a match.

List jobs¶

GET /api/v1/teams/{team_id}/analysis-jobs/

Response 200: {"results": [job, …]}, with every job in the team. Not paginated, and the order isn't guaranteed.

Get a job¶

GET /api/v1/teams/{team_id}/analysis-jobs/{job_id}/

Response 200: the job. Poll this every 5–10 seconds until status is completed, failed or cancelled.

Cancel a job¶

POST /api/v1/teams/{team_id}/analysis-jobs/{job_id}/cancel/

Cancels a job that hasn't started running, pending or queued. No body.

Response 200: the job, now cancelled. A job that starts in the moment the cancel arrives is stopped by it.

Errors

Get a result¶

GET /api/v1/teams/{team_id}/analysis-jobs/{job_id}/result/

Response 200

{
  "job_id": "1b7e…",
  "metrics": {
    "solution": { "…": "the analysis's outputs, in the image's units" }
  }
}

What's inside solution depends on the analysis. Results lists every analysis's keys and units.

Errors

The job object¶

{
  "id": "1b7e5c2a-8d4f-4e1b-9a3c-6f2d8e0b4a7c",
  "image_id": "9d2b6f0e-1c3a-4e5b-8f7d-2a4c6e8b0d1f",
  "analysis_type": "diffusivity",
  "status": "completed",
  "parameters": {
    "direction": "z",
    "target_relative_error": 0.001,
    "solver_tolerance": 1e-05,
    "queue_name": "tortuosity-jl",
    "compute_tier": "auto",
    "backend": "gpu",
    "…": "…"
  },
  "progress_percentage": 100,
  "error_message": "",
  "queue_reason": null,
  "created_at": "2026-10-10T14:10:05.120331+00:00",
  "started_at": "2026-10-10T14:10:06.004512+00:00",
  "completed_at": "2026-10-10T14:12:41.775018+00:00",
  "selected_compute_tier": "gpu-48gb-rtx-8000",
  "solver_converged": true,
  "solver_iterations_completed": 214,
  "solver_wall_time_seconds": null,
  "solver_convergence_telemetry": {},
  "solver_version": "0.3.0",
  "worker_image_tag": "…",
  "worker_image_digest": "sha256:…",
  "worker_application_revision": "…",
  "compute_hardware": "Quadro RTX 8000"
}

This job asked for Auto, and when it was dispatched a 48 GB RTX 8000 GPU was idle and fitted the image, so it ran there.