# Preview an Auto model rule

Show what an Auto model rule would pick, before or after it is saved. Auto scores six fixed sample messages — from small talk to a hard reasoning task — against the rule at an organisation, department or assistant scope, and returns each pick with its estimated cost and time to the first word. Send the unsaved `settings` to preview an edit; leave them out to preview the saved rule. Add `custom_message` to also see what Auto would do with a message of your own. See [Auto Model](/docs/documentation/core-concepts/auto-model).

The six samples cost nothing. A custom message makes one small billed analysis of the message, cached for 10 minutes for the same text. The preview runs on the rule layers only: a person's or chat's own choice is not applied.

## Authentication

Requires authentication (Bearer token or `x-api-key`). Organisation and department scopes need the `manage_users` capability; an assistant scope is also open to that assistant's editors. Requires the Auto model to be switched on for the organisation.

#### Path Parameters

**`organization_id`** string required

The organisation (`org_` prefix).

#### Request Body

**`scope`** object required

The rule being previewed: `type` (`organization`, `department` or `assistant`) and `id`.

**`settings`** object optional

An unsaved rule's settings, the same shape as on [Create or replace an Auto model rule](/docs/api-reference/auto-model/update-rule) and checked by the same rules (`AUTO_MODEL_RULE_INVALID`, `AUTO_MODEL_MODEL_NOT_ALLOWED` with `details.models`, `AUTO_MODEL_EFFORT_RANGE_EMPTY`). Omit to preview the saved rule.

**`enforced`** boolean optional

The unsaved rule's `enforced`; omit to use the saved value.

**`people_can_choose`** boolean optional

The unsaved rule's `people_can_choose`; omit to use the saved value.

**`custom_message`** string optional

A message of your own (1 to 4000 characters) to preview beside the samples.

## Returns

Returns `200 OK` with:

**`scope`** object — `type`, `id`, `name`.

**`enabled`** boolean — Whether Auto is on for this scope under the previewed rule.

**`preset`** string and **`weights`** object — The priority the preview ran with.

**`messages`** array — The six samples, each: `id`, `text`, `tag` (a short label in the reader's language), `status` (`routed` or `pool_empty`), `pick` (`model`, `model_title`, `effort`, `speed_tier`, or `null`), `cost_chf` (CHF, 4 decimals, or `null`), `first_word_s` (seconds, or `null`), `meets_quality` (whether the pick fully meets what the message needs) and `empty_reason` (when no model fits: `rule` — the layer to change, as `layer`, `scope_id`, `name` — and `why`: `pool`, `capabilities`, `effort` or `cost_limit`).

**`custom`** object or null — Your own message, the same fields as a sample plus `signals` (`difficulty`, `task`, `deep_reasoning`, `stakes`, `quick_reply`) and `basis` (`jev` for a full read, `heuristic` for a quick read). `null` without `custom_message`.

**`averages`** object — Over the routed samples: `cost_chf`, `first_word_s`, `meets_quality` (how many met the quality they need), `routed` (how many were routed) and `count` (how many samples).

The example response shows three of the six samples.

Request

```bash cURL
curl -X POST https://api.aitronos.com/v1/organizations/org_7d2c9e41a5b84f0e/auto-model/simulate \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": {"type": "department", "id": "dept_5a1c7e2b9d4f4a8e"},
    "settings": {"preset": "lower_cost", "max_chf_per_message": "0.10"}
  }'
```


```python Python SDK
from aitronos import Aitronos

client = Aitronos(api_key="your-api-key")

preview = client.auto_model.simulate_auto_model_rule(
    organization_id="org_7d2c9e41a5b84f0e",
    scope={"type": "department", "id": "dept_5a1c7e2b9d4f4a8e"},
    settings={"preset": "lower_cost", "max_chf_per_message": "0.10"},
)
print(preview["averages"])
```


```python Python
import os
import requests

response = requests.post(
    "https://api.aitronos.com/v1/organizations/org_7d2c9e41a5b84f0e/auto-model/simulate",
    headers={"X-API-Key": os.environ["FREDDY_API_KEY"]},
    json={
        "scope": {"type": "department", "id": "dept_5a1c7e2b9d4f4a8e"},
        "settings": {"preset": "lower_cost", "max_chf_per_message": "0.10"},
    },
)
for sample in response.json()["messages"]:
    print(sample["tag"], sample["pick"])
```


```javascript JavaScript
const response = await fetch(
  'https://api.aitronos.com/v1/organizations/org_7d2c9e41a5b84f0e/auto-model/simulate',
  {
    method: 'POST',
    headers: { 'X-API-Key': process.env.FREDDY_API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      scope: { type: 'department', id: 'dept_5a1c7e2b9d4f4a8e' },
      settings: { preset: 'lower_cost', max_chf_per_message: '0.10' },
    }),
  },
);
const preview = await response.json();
console.log(preview.averages);
```

200 OK

```json
{
  "scope": {"type": "department", "id": "dept_5a1c7e2b9d4f4a8e", "name": "Support"},
  "enabled": true,
  "preset": "lower_cost",
  "weights": {"quality": 0.25, "speed": 0.1, "cost": 0.65},
  "messages": [
    {"id": "s1", "text": "Thanks, that's perfect", "tag": "Small talk", "status": "routed", "pick": {"model": "ftg-4-light", "model_title": "FTG 4 Light", "effort": "off", "speed_tier": "standard"}, "cost_chf": "0.0005", "first_word_s": 0.4, "meets_quality": true, "empty_reason": null},
    {"id": "s5", "text": "Find the race condition in this Python worker", "tag": "Coding, hard", "status": "routed", "pick": {"model": "ftg-4", "model_title": "FTG 4", "effort": "medium", "speed_tier": "standard"}, "cost_chf": "0.0554", "first_word_s": 2.8, "meets_quality": true, "empty_reason": null},
    {"id": "s6", "text": "Prove the inequality holds for every n ≥ 3", "tag": "Maths, frontier", "status": "pool_empty", "pick": null, "cost_chf": null, "first_word_s": null, "meets_quality": false, "empty_reason": {"rule": {"layer": "department", "scope_id": "dept_5a1c7e2b9d4f4a8e", "name": "Support"}, "why": "cost_limit"}}
  ],
  "custom": null,
  "averages": {"cost_chf": "0.0213", "first_word_s": 1.2, "meets_quality": 5, "routed": 5, "count": 6}
}
```

Errors

```json 422 Unprocessable Entity
{
  "success": false,
  "error": {
    "code": "AUTO_MODEL_MODEL_NOT_ALLOWED",
    "message": "One of the picked models isn't allowed here.",
    "type": "validation_error",
    "status": 422,
    "details": {"models": ["ftg-4-pro"]},
    "trace_id": "2f1e0d9c-8b7a-4c6d-9e5f-4a3b2c1d0e9f",
    "timestamp": "2026-10-27T04:51:34Z"
  }
}
```


```json 422 Unprocessable Entity (effort)
{
  "success": false,
  "error": {
    "code": "AUTO_MODEL_EFFORT_RANGE_EMPTY",
    "message": "This thinking-effort range doesn't overlap the range set above it.",
    "type": "validation_error",
    "status": 422,
    "details": {"inherited": {"min": "low", "max": "high"}},
    "trace_id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
    "timestamp": "2026-10-27T04:51:34Z"
  }
}
```


```json 422 Unprocessable Entity (settings)
{
  "success": false,
  "error": {
    "code": "AUTO_MODEL_RULE_INVALID",
    "message": "This Auto model rule isn't valid. Check the highlighted setting.",
    "type": "validation_error",
    "status": 422,
    "details": {"field": "settings", "reason": "value_error"},
    "trace_id": "641d4f27-68ac-4da5-893a-4c5a36b4f3c3",
    "timestamp": "2026-10-27T04:51:34Z"
  }
}
```


```json 403 Forbidden
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You don't have permission to perform this action.",
    "type": "authorization_error",
    "status": 403,
    "details": {"required_capability": "manage_users"},
    "trace_id": "530b1fa9-6669-41ee-9f05-d03771dda6ec",
    "timestamp": "2026-10-27T04:52:06Z"
  }
}
```


```json 404 Not Found
{
  "success": false,
  "error": {
    "code": "AUTO_MODEL_SCOPE_NOT_FOUND",
    "message": "We couldn't find that department or assistant in this organisation.",
    "type": "client_error",
    "status": 404,
    "details": {"scope_type": "department", "scope_id": "dept_doesnotexist"},
    "trace_id": "9c729929-ce98-41c6-8b7d-142d9a13862f",
    "timestamp": "2026-10-27T04:51:33Z"
  }
}
```


```json 404 Not Found (switched off)
{
  "success": false,
  "error": {
    "code": "AUTO_MODEL_NOT_ENABLED",
    "message": "Auto isn't available for this organisation.",
    "type": "client_error",
    "status": 404,
    "details": {"feature": "auto_model"},
    "trace_id": "5c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
    "timestamp": "2026-10-27T04:51:33Z"
  }
}
```

## Related Resources

- [Auto Model concept](/docs/documentation/core-concepts/auto-model)
- [Create or replace an Auto model rule](/docs/api-reference/auto-model/update-rule)
- [Get an Auto model rule](/docs/api-reference/auto-model/get-rule)
- [List Auto model rules](/docs/api-reference/auto-model/list-rules)
- [Get the Auto model option catalogue](/docs/api-reference/auto-model/get-catalog)