---
title: Models
description: List trained CV models in your organization and download their ONNX weights.
section: API Reference
order: 6
---
Models are produced by [training runs](/docs/api-reference/training.md).
The SDK doesn't insert model rows directly — you train, then read.

```python
from pictograph import Client
client = Client()
```

## list / iter

```python
models = client.models.list(limit=20)
for m in models:
    print(m.name, m.architecture, m.status, m.metrics)

# Or auto-page:
for m in client.models.iter(page_size=50):
    print(m.id, m.model_type)
```

| Arg | Type | Default | Notes |
|---|---|---|---|
| `limit` | `int` | `50` | Backend cap: 500 |
| `status` | `ModelStatus \| None` | `None` | `"training"` / `"ready"` / `"failed"` / `"archived"` |
| `model_type` | `ModelType \| None` | `None` | `"object_detection"` / `"semantic_segmentation"` / `"instance_segmentation"` / `"classification"` |

## get

```python
model = client.models.get("model-uuid")
print(model.architecture, model.metrics["mAP"], model.class_mapping)
```

Returns `Model`. Inspect `metrics` (mAP, precision, recall) and
`class_mapping` (index → class name) for inference setup.

## download

Stream the ONNX weights to a local file. Only `status="ready"` models
are downloadable — `training` / `failed` raise `409 ConflictError`.

```python
from pathlib import Path

client.models.download("model-uuid", output_path=Path("./yolox.onnx"))
```

| Arg | Type |
|---|---|
| `model_id` | `str` |
| `output_path` | `str \| Path` |

The download is chunked and checksummed against the object MD5. Safe
for multi-GB models.

## delete

```python
client.models.delete("model-uuid")
```

Soft-delete (sets `status="archived"`). Weights are not purged on
soft-delete — contact support to permanently remove them.

## Status lifecycle

| `status` | Meaning |
|---|---|
| `training` | Training is in progress; `download` returns 409. |
| `ready` | Trained successfully; weights downloadable via `download()`. |
| `failed` | Training stopped with an error. Inspect the source `TrainingRun.error_message`. |
| `archived` | Soft-deleted. Hidden from `list()` unless `status="archived"` filter passed. |

## Inference

The SDK ships read access only — there is no `client.models.infer()`
endpoint in v1.0.0. To run inference, download the ONNX file and use
your own runtime (`onnxruntime`, `tensorrt`, etc.):

```python
import onnxruntime as ort

client.models.download(model.id, output_path="./model.onnx")
session = ort.InferenceSession("./model.onnx")
# … standard ORT inference loop
```

The `image_inference` credit operation (~1 cr/image) reserved for a
future managed inference endpoint — not yet exposed.

## Common errors

| Status | Exception | Cause |
|---|---|---|
| 404 | `NotFoundError` | `model_id` missing or belongs to another org |
| 409 | `ConflictError` | `download` on a non-`ready` model |