---
title: "Create Predict"
method: POST
path: "/predict"
tags: ["predict"]
---

# Create Predict

`POST /predict`

Create and execute a prediction-only job. Distinct from `/pipeline`:
runs prediction (and the minimum upstream prep, if needed), but exposes
a separate session lifecycle and result endpoints. Use `/pipeline` for
the full classify/apply flow.

Two input modes (auto-detected at job start):

* **Mode A — dataset already prepared.** Triggered when `dataset_path`
  points at a readable dataset.jsonl, or when an existing `session_id`
  has `cache/dataset/dataset.jsonl` whose referenced images resolve.
  Only the predict step runs.
* **Mode B — USD upload / s3_uri / fresh session_id.** When no runnable
  session dataset is present, /predict runs the minimum upstream steps
  (`optimize_usd` if enabled → `identify_asset` → `build_dataset_usd` →
  `build_dataset_prepare_dataset`) before predicting. `apply_physics`
  is intentionally not part of /predict — use POST /pipeline if you
  need the full classify/apply flow.

  A cached JSONL whose images do not resolve falls back to Mode B when
  an input USD is available. Without an input USD, the request returns
  HTTP 400 with recovery guidance.

The detected mode is persisted to session metadata under `predict_mode`
and surfaced in the `GET /predict/{id}/results` response.

## Response `202`

Predict job accepted and queued for execution.

- SessionCreated — Response when session is created.
  - `session_id` string, required
  - `status` string
  - `message` string
  - `estimated_duration_minutes` integer, nullable — Estimated completion time

## Other responses

- `400` — Missing/invalid input — no usd_file/session_id/s3_uri/dataset_path, ambiguous combinations (e.g. usd_file + s3_uri, dataset_path + s3_uri), invalid USD extension, missing dataset, unknown Mode-B render backend, invalid optimizer config, or a cached dataset whose images are unavailable with no input USD to rebuild from.
- `403` — dataset_path resolves outside allowed roots; client S3 URI rejected by the configured bucket allowlist; or S3 access denied.
- `404` — Session not found, or S3 object not found.
- `409` — Predict is already pending/running/cancelling for the supplied session_id, OR the same-pod JobRegistry rerun race-guard fired (the slot was reserved by a concurrent /predict on this instance). Wait for a terminal state or cancel first.
- `413` — Upload or S3 file exceeds the configured size limit.
- `422` — Validation Error
- `500` — Internal failure staging the upload, dataset, or session.
- `502` — Failed to download from S3 upstream.

## Changes

- **2026-07-21** `14f08fb85d12` — 1 breaking, 6 info
  - request property `render_backend` was restricted to a list of enum values
  - added the new `` enum value to the request property `render_backend`
  - added the new `mock` enum value to the request property `render_backend`
  - added the new `ovrtx` enum value to the request property `render_backend`
  - …3 more
- **2026-05-27** `bef81aa36f74` — 1 info
  - endpoint added
- **2026-04-29** `0ba9e71b823c` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/nvidia/apis/physics-agent-service/changes/predict/post.md)

---

[API](https://skmtc.dev/nvidia/apis/physics-agent-service.md) · [All operations](https://skmtc.dev/nvidia/apis/physics-agent-service/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nvidia/physics-agent-service/revisions/47f3bc191c91/schema)