---
title: "Create an instance group"
method: POST
path: "/v1/instance-groups"
tags: ["Instance groups"]
---

# Create an instance group

`POST /v1/instance-groups`

## Request

- Base URL: `https://api.verda.com`
- URL: `https://api.verda.com/v1/instance-groups`
- Auth: HTTP bearer

Creates a project-scoped group with a name, description, location, instance type and template.

## Request body

- CreateInstanceGroupDto
  - `name` string, required
  - `description` string
  - `location_code` string, required
  - `instance_type` string, required: A known instance type code. Fixed for the life of the group.
  - `template` InstanceGroupTemplateDto, required
    - `image` string, required
    - `os_volume` InstanceGroupOsVolumeDto
      - `size` number, required: Default and minimum OS volume size in GB for instances created in this group.
    - `ssh_key_ids` string[]: Default SSH keys for instances created from this group.
    - `startup_script_id` string: Default startup script for instances created from this group.

## Response `201`

- InstanceGroupResponseDto
  - `id` string, required
  - `project_id` string, required
  - `name` string, required
  - `description` object, nullable, required
  - `location_code` string, required
  - `instance_type` string, required
  - `template` object, required: The instance template stored by the group.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `deleted_at` object, nullable, required: Non-null only on a tombstoned group. Public and internal reads return live groups only.
  - `instances` GroupInstanceResponseDto[], required
    - `id` string, required
    - `hostname` string, required
    - `status` string, required
  - `size` number, required: Number of live instances in the group.

## Changes

- **2026-10-15** `416768e2fdd7`: 2 breaking
  - the `deleted_at` response's property type changed from `string` to `object`, and format from `date-time` to no format for status `201`
  - the `description` response's property type changed from `string` to `object` for status `201`
- **2026-10-07** `feda601a5b19`: 1 warning, 2 info
  - removed the request property `template/os_volume/type`
  - added the required property `instances` to the response with the `201` status
  - added the required property `size` to the response with the `201` status
- **2026-09-11** `72a1484b52da`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/datacrunch/apis/verda-cloud-public-api/changes/v1/instance-groups/post.md)

---

[API](https://skmtc.dev/datacrunch/apis/verda-cloud-public-api.md) - [All operations](https://skmtc.dev/datacrunch/apis/verda-cloud-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/datacrunch/apis/verda-cloud-public-api/revisions/6c2e4addd240?raw)