> For the complete documentation index, see [llms.txt](https://docs.projectsim.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.projectsim.ai/creating-assets/batches.md).

# Asset batches

`POST /v1/batches/standard` · `POST /v1/batches/measured`

Create several independent assets in one request and track them as a batch. Each item follows the same input and parameter rules as the [Standard asset](/creating-assets/assets-standard.md) or [Measured asset](/creating-assets/assets-measured.md) endpoint. Even a list of one creates a batch; use those single-asset endpoints when you only need one asset and job ID.

Creation is all-or-nothing: an invalid item rejects the entire request. One `Idempotency-Key` covers the batch; retrying the same request with that key returns the same batch and member IDs.

## Input

| Field                       | Notes                                                                                                                                                                                                                                                         |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `items` (required)          | List of 1–100 asset requests. If your account has a lifetime asset limit, the whole batch is reserved against it up front; a batch that would cross it returns `429` `asset-limit-reached` and creates nothing. The request body is capped at 832 MB (`413`). |
| `name`                      | Optional batch display label (≤ 100 chars).                                                                                                                                                                                                                   |
| `items[].inputs` (required) | Standard: one image or nonblank text, never both. Measured: one image and one ChArUco capture video; text is not accepted. See [Standard inputs](/creating-assets/assets-standard.md#input) and [Measured inputs](/creating-assets/assets-measured.md#input). |
| `items[].name`              | Optional display label for that asset (≤ 100 chars).                                                                                                                                                                                                          |
| `items[].params`            | Optional output settings for that asset; see [Parameters that apply](#parameters-that-apply).                                                                                                                                                                 |
| `Idempotency-Key` (header)  | Makes retries safe for the whole batch; reusing a key with a different request returns `409`.                                                                                                                                                                 |

## Parameters that apply

Each item accepts `params` with `mesh`, `texture`, and `physics` settings, just like the [Standard](/creating-assets/assets-standard.md#parameters-that-apply) and [Measured](/creating-assets/assets-measured.md#parameters-that-apply) endpoints. Different items can use different settings. Set `params` inside each item; there is no batch-level `params` field. Omit it to use defaults. See [Parameters](/creating-assets/parameters.md) for supported values and combinations.

## Examples

### Standard batch

Send this body to `POST /v1/batches/standard`. The first item uses an image; the second uses text. Each sets its own output parameters.

```json
{
  "name": "warehouse props",
  "items": [
    {
      "name": "chair",
      "inputs": {
        "images": [{"url": "https://example.com/chair.png"}]
      },
      "params": {
        "mesh": {"quality": "low"},
        "physics": {"simulator": "isaac_sim_physx"}
      }
    },
    {
      "name": "toolbox",
      "inputs": {"text": "a red steel toolbox"},
      "params": {
        "texture": {"resolution": 2048},
        "physics": {"simulator": "mujoco"}
      }
    }
  ]
}
```

### Measured batch

Send this body to `POST /v1/batches/measured`. Every item needs an image and a capture video. See [Capturing an asset](/creating-assets/assets-measured/measured-capture.md) for capture instructions.

```json
{
  "name": "measured props",
  "items": [
    {
      "name": "ceramic pitcher",
      "inputs": {
        "images": [{"url": "https://example.com/pitcher.png"}],
        "capture": [{"url": "https://example.com/pitcher_charuco.mov"}]
      },
      "params": {
        "mesh": {"quality": "standard"},
        "physics": {"simulator": "isaac_sim_physx"}
      }
    }
  ]
}
```

Both endpoints return `202` with the batch `id`, parent `job_id`, `status_url`, and `assets` in input order.

## Poll once for the whole batch

`GET /v1/batches/{id}` returns status, member counts, progress and a manifest link when finalized (valid 24 hours; poll again to refresh it). Counts include `requested` (the batch size) plus `queued`, `running`, `complete`, `failed`, and `canceled`. Progress is the fraction of members that are terminal, not the fraction that succeeded.

* `queued`: awaiting dispatch, and briefly again once every member has settled, while the manifest waits to be written.
* `running`: executing members or preparing the manifest.
* `complete`: all members succeeded and the manifest is available.
* `partial`: some succeeded and some failed or were canceled.
* `failed`: no members succeeded, or an unrecoverable parent error occurred.
* `canceled`: the batch was canceled or all members were canceled.

One failed member does not stop other members. The batch job remains active until its members settle and finalization finishes. ZIP bundles are not available in this release.

## Cancel and webhooks

`POST /v1/jobs/{job_id}/cancel` with the batch's parent `job_id` cancels every unfinished member, but only until any member starts generating; after that it is a `409` `job-started`. Each member's own `job_id` can also be canceled individually until that member starts. Canceled assets don't count toward your asset limit.

Webhook subscribers receive `batch.completed` (for `complete` or `partial`), `batch.failed`, or `batch.canceled` when the batch settles, and the usual `asset.*` events for each member. See [Webhooks](/guides/webhooks.md).

## Page through assets and download files

`GET /v1/batches/{id}/assets?limit=50&cursor=50&status=complete`

`limit` is 1–100 (default 50). Omit `cursor` for the first page, then pass the returned `next_cursor`; null means there are no more matching members. `status` is optional. Members are ordered by their stable, one-based `batch_index`, even when some failed or a filter produces gaps.

Each `members` entry includes `batch_index`, `asset_id`, `job_id`, `status`, `current_stage`, `error`, and `files`. File entries contain the kind, relative package path, fresh download URL and expiry. Preserve the relative paths when downloading a USD and its textures. Download URLs last 24 hours; fetch the page again to refresh them.

Deleted assets are omitted from member pages. Aggregate counts and the manifest retain the original execution outcomes. Both endpoints enforce batch ownership.

Creation accepts up to 100 items, subject to account quota and the 832 MB request limit. High-fidelity variation sets accept 1–100 members; procedural sets accept 10–500.