# Model Routes Commands

> See [Model Routes module docs](../../modules/model-routes) for permissions and data model.

# Model Routes Commands

See [Model Routes module docs](../../modules/model-routes) for permissions and data model.

### `soat list-model-routes`

List model routes

- Method: `GET`
- Path: `/api/v1/model-routes`

#### Usage

```bash
soat list-model-routes
```

#### Options

##### `--project-id`

Project ID (required if not using project key auth)

- Source: `query`
- Required: no
- Type: `string`
- Example: `proj_V1StGXR8Z5jdHi6B`

##### `--limit`

Maximum number of results to return

- Source: `query`
- Required: no
- Type: `integer`
- Default: `50`

##### `--offset`

Number of results to skip

- Source: `query`
- Required: no
- Type: `integer`
- Default: `0`

### `soat create-model-route`

Create a model route

- Method: `POST`
- Path: `/api/v1/model-routes`

#### Usage

```bash
soat create-model-route --name <string> --targets <array<object>>
```

#### Options

##### `--project-id`

Project ID (required if not using project key auth)

- Source: `body`
- Required: no
- Type: `string`
- Example: `proj_V1StGXR8Z5jdHi6B`

##### `--name`

Human-readable name, unique per project

- Source: `body`
- Required: yes
- Type: `string`
- Example: `primary-with-fallback`

##### `--targets`

Ordered failover targets. Position is priority: target 0 is tried first, and a retryable failure falls through to the next target.

- Source: `body`
- Required: yes
- Type: `array<object>`

##### `--retry-on`

Which failure classes are failover-eligible. A failure whose class is not listed (and every deterministic failure — 400-class, auth, content policy) fails the generation immediately instead of spending another target's budget.

- Source: `body`
- Required: no
- Type: `array<enum("provider_error", "timeout", "rate_limited")>`
- Default: `["provider_error","timeout","rate_limited"]`

##### `--failure-threshold`

Consecutive retryable failures after which a target is skipped for `cooldown_seconds`. Breaker state is in-process per node and keyed by (provider, model), so it is shared by every route pointing at the same backend.

- Source: `body`
- Required: no
- Type: `integer`
- Default: `3`
- Example: `3`

##### `--cooldown-seconds`

How long a tripped target is skipped before being probed again

- Source: `body`
- Required: no
- Type: `integer`
- Default: `60`
- Example: `60`

### `soat get-model-route`

Get a model route

- Method: `GET`
- Path: `/api/v1/model-routes/{route_id}`

#### Usage

```bash
soat get-model-route --route-id <string>
```

#### Options

##### `--route-id`

Model route ID

- Source: `path`
- Required: yes
- Type: `string`
- Example: `route_V1StGXR8Z5jdHi6B`

### `soat update-model-route`

Update a model route

- Method: `PUT`
- Path: `/api/v1/model-routes/{route_id}`

#### Usage

```bash
soat update-model-route --route-id <string>
```

#### Options

##### `--route-id`

Model route ID

- Source: `path`
- Required: yes
- Type: `string`

##### `--name`

New name (unique per project)

- Source: `body`
- Required: no
- Type: `string`

##### `--targets`

Replacement target list (ordered)

- Source: `body`
- Required: no
- Type: `array<object>`

##### `--retry-on`

—

- Source: `body`
- Required: no
- Type: `array<enum("provider_error", "timeout", "rate_limited")>`

##### `--failure-threshold`

—

- Source: `body`
- Required: no
- Type: `integer`

##### `--cooldown-seconds`

—

- Source: `body`
- Required: no
- Type: `integer`

### `soat delete-model-route`

Delete a model route

- Method: `DELETE`
- Path: `/api/v1/model-routes/{route_id}`

#### Usage

```bash
soat delete-model-route --route-id <string>
```

#### Options

##### `--route-id`

Model route ID

- Source: `path`
- Required: yes
- Type: `string`