# Change an agent's hosting settings

Source: https://docs.vlayers.ai/reference/hosting/update-agent-hosting

`PUT /v1/agents/{id}/hosting` · scope `workspace:write`

Sets the room size, the number of warm rooms and, optionally, a lower call capacity for an agent. The change applies to the rooms started from now on and rolls the running ones one at a time. A setting your plan does not allow is refused with 422 and names the limit.

Requires an API key with the `workspace:write` scope.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | The agent id. Example: `"0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78"` |
| `sizeClass` | body | "small" \| "medium" \| "large" | yes | The room size: `small`, `medium` or `large`. `GET /v1/agents/{id}/hosting` lists what your plan allows and what each costs per hour. |
| `warmCount` | body | integer | yes | How many rooms to keep ready for each version that takes traffic, at least 1. Every room is billed while it runs. |
| `maxInFlight` | body | integer | yes | Lower the number of calls one room takes at once below the size's own; `null` keeps the size's number. |
| `sleepAfterIdleMinutes` | body | integer | no | Sleep when unused: the agent's rooms stop after this many minutes (5 to 10080) with no call, text, request or schedule, and start again on the next one, which waits a few seconds. `null` is always on: refused here for an agent that sleeps (use `POST /v1/agents/{id}/hosting/always-on`, so the price is seen first), and kept for one that is already always on. Leave it out to keep the current value. |

## Request

cURL:

```bash
curl -X PUT "https://api.vlayers.ai/v1/agents/$AGENT_ID/hosting" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sizeClass": "small",
    "warmCount": 2,
    "maxInFlight": null
  }'
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { settings } = await voicelayer.hosting.updateAgent('<agent-id>', {
  sizeClass: 'small',
  warmCount: 2,
  maxInFlight: null
});
console.log(settings);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.hosting.update_agent(
    "<agent-id>",
    size_class="small",
    warm_count=2,
    max_in_flight=None,
)
print(result.settings)
```

## Response `200`

```json
{
  "agentId": "0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78",
  "settings": {
    "sizeClass": "small",
    "warmCount": 2,
    "maxInFlight": null,
    "sleepAfterIdleMinutes": 60
  },
  "lastActiveAt": null,
  "isDefault": false,
  "classes": [
    {
      "sizeClass": "small",
      "allowed": true,
      "priceUsdPerHour": 0.03,
      "cpuGuaranteedMillicores": 250,
      "memoryMiB": 512,
      "maxInFlight": 8
    },
    {
      "sizeClass": "medium",
      "allowed": true,
      "priceUsdPerHour": 0.06,
      "cpuGuaranteedMillicores": 500,
      "memoryMiB": 1024,
      "maxInFlight": 16
    }
  ],
  "maxRooms": 5,
  "roomsInUse": 1,
  "concurrentCalls": 16,
  "hourlyUsd": 0.06,
  "rooms": [
    {
      "id": "room_0192f5d4-8b9c-7dae-8f3a-4b5c6d7e8f90",
      "workspaceId": "0192f5a1-5e6f-7a7b-8c8d-9e0f1a2b3c45",
      "environment": "prd",
      "agentId": "0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78",
      "versionId": "0192f5d5-9cad-7ebf-9a4b-5c6d7e8f9012",
      "manifestHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "imageDigest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "replica": 0,
      "sizeClass": "small",
      "purpose": "warm",
      "state": "ready",
      "runtimeClass": "kata-clh-4-2",
      "shimVersion": "1.0.0",
      "replacementOf": null,
      "createdAt": "2026-10-20T15:04:05.000Z",
      "endedAt": null
    }
  ],
  "refusals": [],
  "walletEmpty": null,
  "logRetentionDays": 14
}
```
