Instances

Get Instances

get

Get all instances for a project

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

next_cursorany · nullableOptional

sort_bystring · enum · nullableOptionalPossible values:

sort_dirstring · enum · nullableOptionalPossible values:

projectstringRequired

instance_typestring · nullableOptionalExample: it_abc123456

regionstring · nullableOptionalExample: us-central1-a

bid_fid_instring[] · nullableOptional

Comma-separated list of bid FIDs

reservation_fid_instring[] · nullableOptional

Comma-separated list of reservation FIDs

limitinteger · min: 1 · max: 100 · nullableOptional

Responses

200

Successful Response

application/json

next_cursorstring · nullableOptional

422

Validation Error

application/json

get/v2/instances

GET /v2/instances?project=text HTTP/1.1
Host: api.mithril.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "fid": "inst_abc123456",
      "name": "text",
      "project": "proj_abc123456",
      "created_at": "2024-01-01T00:00:00Z",
      "created_by": "user_abc123456",
      "instance_type": "it_abc123456",
      "region": "us-central1-a",
      "bid": "bid_abc123456",
      "reservation": "res_abc123456",
      "ssh_destination": "text",
      "private_ip": "text",
      "status": "STATUS_NEW"
    }
  ],
  "next_cursor": "text"
}

Put Instance Status

patch

Trigger a status change for a set of instances.

This endpoint supports batch start and pause requests for instances. The request accepts a set of instance FIDs and a target action (STATUS_RUNNING or STATUS_PAUSED).

The response always includes an entry for every requested instance, keyed by instance FID, with that instance's current status after processing.

When an instance is successfully starting, its status is STATUS_CONFIRMED.
When an instance is successfully stopping, its status is STATUS_STOPPING.
If an instance cannot be stopped, its prior status is returned unchanged.

Paused instances which are associated with a reservation will accrue a credit based on the flexible usage buyback price on that reservation.

Notes:

Only reserved instances are supported at this time.
This API is asynchronous. You can check the status of the instance with the Get Status api.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

instancesstring[]Required

statusstring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

404

One of the provided instances did not exist.

409

One or more of the instances is not yet ready for this operation.

422

Validation Error

application/json

501

Spot bids are not yet supported.

patch/v2/instances

PATCH /v2/instances HTTP/1.1
Host: api.mithril.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 58

{
  "instances": [
    "inst_abc123456"
  ],
  "status": "STATUS_RUNNING"
}

{
  "instances": {
    "ANY_ADDITIONAL_PROPERTY": "STATUS_NEW"
  }
}

Get Instance Status

get

Get the status of a specific instance by its ID. Supports authentication via mithril key or API key.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

instance_fidstringRequiredExample: inst_abc123456

Responses

200

Successful Response

application/json

Response model for instance status endpoint.

fidstringRequiredExample: inst_abc123456

namestringRequired

statusstring · enumRequiredExample: STATUS_NEWPossible values:

bidstring · nullableOptionalExample: bid_abc123456

reservationstring · nullableOptionalExample: res_abc123456

end_timestring · datetime · nullableOptionalExample: 2024-01-01T00:00:00Z

422

Validation Error

application/json

get/v2/instances/{instance_fid}/status

GET /v2/instances/{instance_fid}/status HTTP/1.1
Host: api.mithril.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "fid": "inst_abc123456",
  "name": "text",
  "status": "STATUS_NEW",
  "bid": "bid_abc123456",
  "reservation": "res_abc123456",
  "end_time": "2024-01-01T00:00:00Z"
}

Refresh Instance Boot Disk

post

Refresh (delete and recreate) the boot disk of a reserved instance.

The instance must already be stopped: stop it first via the pause API (PATCH /instances with STATUS_PAUSED), then call this endpoint, then start it again. A running instance is declined; this endpoint never stops the instance itself. When image_version is omitted the current boot image is reused.

Notes:

Only reserved (non-spot) instances are supported at this time.
This is being rolled out across all our regions.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

instance_fidstringRequiredExample: inst_abc123456

Body

Request body for the refresh-boot-disk endpoint.

The body is optional; when image_version is omitted the instance's current boot image is reused.

image_versionstring · nullableOptionalExample: imgver_abc123456

Responses

200

Successful Response

application/json

Response model for the refresh-boot-disk endpoint.

fidstringRequiredExample: inst_abc123456

image_versionstring · nullableRequiredExample: imgver_abc123456

statusconst: REFRESHEDRequired

404

The instance does not exist.

409

The instance has no underlying VM to refresh.

422

The instance is still running, or the requested image version is invalid for the instance's region. The body carries a reason of INSTANCE_RUNNING or INVALID_IMAGE_VERSION.

501

Boot disk refresh is not supported for this instance yet (spot instances, or not yet available in this instance's region).

post/v2/instances/{instance_fid}/refresh-boot-disk

POST /v2/instances/{instance_fid}/refresh-boot-disk HTTP/1.1
Host: api.mithril.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 36

{
  "image_version": "imgver_abc123456"
}

{
  "fid": "inst_abc123456",
  "image_version": "imgver_abc123456",
  "status": "text"
}

Get Instance Status History

get

Get the history of a specific instance by its ID, or of all instances in a bid or reservation.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

projectstringRequiredExample: proj_abc123456

instance_fidstring · nullableOptionalExample: inst_abc123456

bid_fidstring · nullableOptionalExample: bid_abc123456

reservation_fidstring · nullableOptionalExample: res_abc123456

limitinteger · min: 1 · max: 100 · nullableOptional

start_timestring · datetime · nullableOptionalExample: 2024-01-01T00:00:00Z

end_timestring · datetime · nullableOptionalExample: 2024-01-01T00:00:00Z

next_cursorstring · nullableOptional

Responses

200

Successful Response

application/json

Response model for instance status history endpoint.

next_cursorstring · nullableOptional

422

Validation Error

application/json

get/v2/instances/status/history

GET /v2/instances/status/history?project=proj_abc123456 HTTP/1.1
Host: api.mithril.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "instances": [
    {
      "instance_fid": "inst_abc123456",
      "events": [
        {
          "timestamp": "2024-01-01T00:00:00Z",
          "status": "STATUS_NEW"
        }
      ],
      "bid_fid": "bid_abc123456",
      "reservation_fid": "res_abc123456"
    }
  ],
  "next_cursor": "text"
}

Get Instance Pricing History

get

Get the pricing history of a specific instance by its ID, or of all instances in a bid or reservation.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

projectstringRequiredExample: proj_abc123456

instance_fidstring · nullableOptionalExample: inst_abc123456

bid_fidstring · nullableOptionalExample: bid_abc123456

reservation_fidstring · nullableOptionalExample: res_abc123456

limitinteger · min: 1 · max: 100 · nullableOptional

start_timestring · datetime · nullableOptionalExample: 2024-01-01T00:00:00Z

end_timestring · datetime · nullableOptionalExample: 2024-01-01T00:00:00Z

next_cursorstring · nullableOptional

Responses

200

Successful Response

application/json

Response model for instance pricing history endpoint.

next_cursorstring · nullableOptional

422

Validation Error

application/json

get/v2/instances/pricing/history

GET /v2/instances/pricing/history?project=proj_abc123456 HTTP/1.1
Host: api.mithril.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "instances": [
    {
      "instance_fid": "inst_abc123456",
      "events": [
        {
          "price_cents": 1,
          "start_time": "2024-01-01T00:00:00Z",
          "end_time": "2024-01-01T00:00:00Z"
        }
      ],
      "bid_fid": "bid_abc123456",
      "reservation_fid": "res_abc123456"
    }
  ],
  "next_cursor": "text"
}

PreviousKubernetes Clusters NextInstance Types

Last updated 9 days ago