> For the complete documentation index, see [llms.txt](https://docs.mithril.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mithril.ai/compute-api/compute-api-reference/instances.md).

# Instances

## Get Instances

> Get all instances for a project

```json
{"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_<key>"}},"schemas":{"SortDirection":{"type":"string","enum":["asc","desc"]},"GetInstancesResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/InstanceModel"},"type":"array","title":"Data"},"next_cursor":{"type":"string","nullable":true}},"type":"object","required":["data"],"title":"GetInstancesResponse"},"InstanceModel":{"properties":{"fid":{"type":"string","title":"Fid"},"name":{"type":"string","title":"Name"},"project":{"type":"string","title":"Project"},"created_at":{"type":"string","format":"datetime","title":"Created At"},"created_by":{"type":"string","title":"Created By"},"instance_type":{"type":"string","title":"Instance Type"},"region":{"type":"string","nullable":true},"bid":{"type":"string","nullable":true},"reservation":{"type":"string","nullable":true},"ssh_destination":{"type":"string","nullable":true},"private_ip":{"type":"string","nullable":true},"status":{"type":"string","enum":["STATUS_NEW","STATUS_CONFIRMED","STATUS_INITIALIZING","STATUS_STARTING","STATUS_RUNNING","STATUS_STOPPING","STATUS_TERMINATED","STATUS_RELOCATING","STATUS_PREEMPTING","STATUS_PREEMPTED","STATUS_REPLACED","STATUS_PAUSED","STATUS_ERROR"],"title":"Status"}},"type":"object","required":["fid","name","project","created_at","created_by","instance_type","status"],"title":"InstanceModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v2/instances":{"get":{"tags":["instances","instances"],"summary":"Get Instances","description":"Get all instances for a project","operationId":"get_instances_v2_instances_get","parameters":[{"name":"next_cursor","in":"query","required":false,"schema":{"nullable":true}},{"name":"sort_by","in":"query","required":false,"schema":{"enum":["created_at","instance_status","instance_type_fid"],"type":"string","nullable":true}},{"name":"sort_dir","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SortDirection","nullable":true}},{"name":"project","in":"query","required":true,"schema":{"type":"string","title":"Project"}},{"name":"instance_type","in":"query","required":false,"schema":{"type":"string","nullable":true}},{"name":"region","in":"query","required":false,"schema":{"type":"string","nullable":true}},{"name":"status_in","in":"query","required":false,"schema":{"type":"array","items":{"enum":["STATUS_NEW","STATUS_CONFIRMED","STATUS_INITIALIZING","STATUS_STARTING","STATUS_RUNNING","STATUS_STOPPING","STATUS_TERMINATED","STATUS_RELOCATING","STATUS_PREEMPTING","STATUS_PREEMPTED","STATUS_REPLACED","STATUS_PAUSED","STATUS_ERROR"],"type":"string"},"description":"Comma-separated list of instance statuses","nullable":true}},{"name":"order_type_in","in":"query","required":false,"schema":{"type":"array","items":{"enum":["Bid","Reservation"],"type":"string"},"description":"Comma-separated list of order types","nullable":true}},{"name":"bid_fid_in","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Comma-separated list of bid FIDs","nullable":true}},{"name":"reservation_fid_in","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Comma-separated list of reservation FIDs","nullable":true}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"nullable":true}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetInstancesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Put Instance Status

> 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\
> &#x20; Get Status api.

```json
{"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_<key>"}},"schemas":{"PatchInstanceStatusRequest":{"properties":{"instances":{"items":{"type":"string"},"type":"array","uniqueItems":true,"title":"Instances"},"status":{"type":"string","enum":["STATUS_RUNNING","STATUS_PAUSED"],"title":"Status"}},"type":"object","required":["instances","status"],"title":"PatchInstanceStatusRequest"},"PatchInstanceStatusResponse":{"properties":{"instances":{"additionalProperties":{"type":"string","enum":["STATUS_NEW","STATUS_CONFIRMED","STATUS_INITIALIZING","STATUS_STARTING","STATUS_RUNNING","STATUS_STOPPING","STATUS_TERMINATED","STATUS_RELOCATING","STATUS_PREEMPTING","STATUS_PREEMPTED","STATUS_REPLACED","STATUS_PAUSED","STATUS_ERROR"]},"propertyNames":{},"type":"object","title":"Instances"}},"type":"object","required":["instances"],"title":"PatchInstanceStatusResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v2/instances":{"patch":{"tags":["instances","instances"],"summary":"Put Instance Status","description":"Trigger a status change for a set of instances.\n\nThis endpoint supports batch start and pause requests for instances. The\nrequest accepts a set of instance FIDs and a target action\n(`STATUS_RUNNING` or `STATUS_PAUSED`).\n\nThe response always includes an entry for every requested instance, keyed by\ninstance FID, with that instance's current status after processing.\n- When an instance is successfully starting, its status is `STATUS_CONFIRMED`.\n- When an instance is successfully stopping, its status is `STATUS_STOPPING`.\n- If an instance cannot be stopped, its prior status is returned unchanged.\n\nPaused instances which are associated with a reservation will accrue a\ncredit based on the flexible usage buyback price on that reservation.\n\nNotes:\n- Only reserved instances are supported at this time.\n- This API is asynchronous. You can check the status of the instance with the\n  Get Status api.","operationId":"put_instance_status_v2_instances_patch","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchInstanceStatusRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchInstanceStatusResponse"}}}},"404":{"description":"One of the provided instances did not exist."},"409":{"description":"One or more of the instances is not yet ready for this operation."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"501":{"description":"Spot bids are not yet supported."}}}}}}
```

## Get Instance Status

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

```json
{"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_<key>"}},"schemas":{"InstanceStatusResponse":{"properties":{"fid":{"type":"string","title":"Fid"},"name":{"type":"string","title":"Name"},"status":{"type":"string","enum":["STATUS_NEW","STATUS_CONFIRMED","STATUS_INITIALIZING","STATUS_STARTING","STATUS_RUNNING","STATUS_STOPPING","STATUS_TERMINATED","STATUS_RELOCATING","STATUS_PREEMPTING","STATUS_PREEMPTED","STATUS_REPLACED","STATUS_PAUSED","STATUS_ERROR"],"title":"Status"},"bid":{"type":"string","nullable":true},"reservation":{"type":"string","nullable":true},"end_time":{"type":"string","format":"datetime","nullable":true}},"type":"object","required":["fid","name","status"],"title":"InstanceStatusResponse","description":"Response model for instance status endpoint."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v2/instances/{instance_fid}/status":{"get":{"tags":["instances","instances"],"summary":"Get Instance Status","description":"Get the status of a specific instance by its ID.\nSupports authentication via mithril key or API key.","operationId":"get_instance_status_v2_instances__instance_fid__status_get","parameters":[{"name":"instance_fid","in":"path","required":true,"schema":{"type":"string","title":"Instance Fid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstanceStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Refresh Instance Boot Disk

> 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.

```json
{"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_<key>"}},"schemas":{"RefreshBootDiskRequest":{"properties":{"image_version":{"type":"string","nullable":true}},"type":"object","title":"RefreshBootDiskRequest","description":"Request body for the refresh-boot-disk endpoint.\n\nThe body is optional; when ``image_version`` is omitted the instance's\ncurrent boot image is reused."},"RefreshBootDiskResponse":{"properties":{"fid":{"type":"string","title":"Fid"},"image_version":{"type":"string","nullable":true},"status":{"type":"string","const":"REFRESHED","title":"Status"}},"type":"object","required":["fid","image_version","status"],"title":"RefreshBootDiskResponse","description":"Response model for the refresh-boot-disk endpoint."}}},"paths":{"/v2/instances/{instance_fid}/refresh-boot-disk":{"post":{"tags":["instances","instances"],"summary":"Refresh Instance Boot Disk","description":"Refresh (delete and recreate) the boot disk of a reserved instance.\n\nThe instance must already be stopped: stop it first via the pause API\n(`PATCH /instances` with `STATUS_PAUSED`), then call this endpoint, then\nstart it again. A running instance is declined; this endpoint never\nstops the instance itself. When `image_version` is omitted the current\nboot image is reused.\n\nNotes:\n- Only reserved (non-spot) instances are supported at this time.\n- This is being rolled out across all our regions.","operationId":"refresh_instance_boot_disk_v2_instances__instance_fid__refresh_boot_disk_post","parameters":[{"name":"instance_fid","in":"path","required":true,"schema":{"type":"string","title":"Instance Fid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshBootDiskRequest","nullable":true}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshBootDiskResponse"}}}},"404":{"description":"The instance does not exist."},"409":{"description":"The instance has no underlying VM to refresh."},"422":{"description":"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":{"description":"Boot disk refresh is not supported for this instance yet (spot instances, or not yet available in this instance's region)."}}}}}}
```

## Get Instance Status History

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

```json
{"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_<key>"}},"schemas":{"InstanceStatusHistoryResponse":{"properties":{"instances":{"items":{"$ref":"#/components/schemas/InstanceStatusHistory"},"type":"array","title":"Instances"},"next_cursor":{"type":"string","nullable":true}},"type":"object","required":["instances"],"title":"InstanceStatusHistoryResponse","description":"Response model for instance status history endpoint."},"InstanceStatusHistory":{"properties":{"instance_fid":{"type":"string","title":"Instance Fid"},"events":{"items":{"$ref":"#/components/schemas/InstanceStatusEvent"},"type":"array","title":"Events"},"bid_fid":{"type":"string","nullable":true},"reservation_fid":{"type":"string","nullable":true}},"type":"object","required":["instance_fid","events"],"title":"InstanceStatusHistory","description":"The history of an instance's status."},"InstanceStatusEvent":{"properties":{"timestamp":{"type":"string","format":"datetime","title":"Timestamp"},"status":{"type":"string","enum":["STATUS_NEW","STATUS_CONFIRMED","STATUS_INITIALIZING","STATUS_STARTING","STATUS_RUNNING","STATUS_STOPPING","STATUS_TERMINATED","STATUS_RELOCATING","STATUS_PREEMPTING","STATUS_PREEMPTED","STATUS_REPLACED","STATUS_PAUSED","STATUS_ERROR"],"title":"Status"}},"type":"object","required":["timestamp","status"],"title":"InstanceStatusEvent","description":"An event in the history of an instance's status."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v2/instances/status/history":{"get":{"tags":["instances","instances"],"summary":"Get Instance Status History","description":"Get the history of a specific instance by its ID,\nor of all instances in a bid or reservation.","operationId":"get_instance_status_history_v2_instances_status_history_get","parameters":[{"name":"project","in":"query","required":true,"schema":{"type":"string","title":"Project"}},{"name":"instance_fid","in":"query","required":false,"schema":{"type":"string","nullable":true}},{"name":"bid_fid","in":"query","required":false,"schema":{"type":"string","nullable":true}},{"name":"reservation_fid","in":"query","required":false,"schema":{"type":"string","nullable":true}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"nullable":true}},{"name":"start_time","in":"query","required":false,"schema":{"type":"string","format":"datetime","nullable":true}},{"name":"end_time","in":"query","required":false,"schema":{"type":"string","format":"datetime","nullable":true}},{"name":"next_cursor","in":"query","required":false,"schema":{"type":"string","nullable":true}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstanceStatusHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get Instance Pricing History

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

```json
{"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_<key>"}},"schemas":{"InstancePricingHistoryResponse":{"properties":{"instances":{"items":{"$ref":"#/components/schemas/InstancePricingHistory"},"type":"array","title":"Instances"},"next_cursor":{"type":"string","nullable":true}},"type":"object","required":["instances"],"title":"InstancePricingHistoryResponse","description":"Response model for instance pricing history endpoint."},"InstancePricingHistory":{"properties":{"instance_fid":{"type":"string","title":"Instance Fid"},"events":{"items":{"$ref":"#/components/schemas/InstancePricingEvent"},"type":"array","title":"Events"},"bid_fid":{"type":"string","nullable":true},"reservation_fid":{"type":"string","nullable":true}},"type":"object","required":["instance_fid","events"],"title":"InstancePricingHistory","description":"The history of an instance's pricing."},"InstancePricingEvent":{"properties":{"price_cents":{"type":"integer","title":"Price Cents"},"start_time":{"type":"string","format":"datetime","title":"Start Time"},"end_time":{"type":"string","format":"datetime","nullable":true}},"type":"object","required":["price_cents","start_time","end_time"],"title":"InstancePricingEvent","description":"A price period in the history of an instance."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v2/instances/pricing/history":{"get":{"tags":["instances","instances"],"summary":"Get Instance Pricing History","description":"Get the pricing history of a specific instance by its ID,\nor of all instances in a bid or reservation.","operationId":"get_instance_pricing_history_v2_instances_pricing_history_get","parameters":[{"name":"project","in":"query","required":true,"schema":{"type":"string","title":"Project"}},{"name":"instance_fid","in":"query","required":false,"schema":{"type":"string","nullable":true}},{"name":"bid_fid","in":"query","required":false,"schema":{"type":"string","nullable":true}},{"name":"reservation_fid","in":"query","required":false,"schema":{"type":"string","nullable":true}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"nullable":true}},{"name":"start_time","in":"query","required":false,"schema":{"type":"string","format":"datetime","nullable":true}},{"name":"end_time","in":"query","required":false,"schema":{"type":"string","format":"datetime","nullable":true}},{"name":"next_cursor","in":"query","required":false,"schema":{"type":"string","nullable":true}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstancePricingHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mithril.ai/compute-api/compute-api-reference/instances.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.