# 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"}}}}}}}}}
```

## 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.