# Spot

## Get Bids

> Get all Spot bids for a project, or all user's projects if not specified

```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"]},"GetBidsResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/BidModel"},"type":"array","title":"Data"},"next_cursor":{"type":"string","nullable":true}},"type":"object","required":["data"],"title":"GetBidsResponse"},"BidModel":{"properties":{"fid":{"type":"string","title":"Fid"},"name":{"type":"string","title":"Name"},"project":{"type":"string","title":"Project"},"created_by":{"type":"string","title":"Created By"},"created_at":{"type":"string","format":"datetime","title":"Created At"},"deactivated_at":{"type":"string","format":"datetime","nullable":true},"limit_price":{"type":"string","title":"Limit Price"},"instance_quantity":{"type":"integer","title":"Instance Quantity"},"instance_type":{"type":"string","title":"Instance Type"},"region":{"type":"string","nullable":true},"instances":{"items":{"type":"string"},"type":"array","title":"Instances"},"launch_specification":{"$ref":"#/components/schemas/LaunchSpecificationModel"},"status":{"type":"string","enum":["Open","Allocated","Preempting","Terminated","Paused"],"title":"Status"}},"type":"object","required":["fid","name","project","created_by","created_at","limit_price","instance_quantity","instance_type","instances","launch_specification","status"],"title":"BidModel"},"LaunchSpecificationModel":{"properties":{"volumes":{"items":{"type":"string"},"type":"array","title":"Volumes","description":"List of volume FIDs"},"ssh_keys":{"items":{"type":"string"},"type":"array","title":"Ssh Keys","description":"List of SSH key FIDs"},"startup_script":{"type":"string","nullable":true},"kubernetes_cluster":{"type":"string","nullable":true},"image_version":{"type":"string","nullable":true},"memory_gb":{"type":"integer","nullable":true}},"type":"object","required":["volumes","ssh_keys"],"title":"LaunchSpecificationModel"},"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/spot/bids":{"get":{"tags":["spot"],"summary":"Get Bids","description":"Get all Spot bids for a project, or all user's projects if not specified","operationId":"get_bids_v2_spot_bids_get","parameters":[{"name":"next_cursor","in":"query","required":false,"schema":{"nullable":true}},{"name":"sort_by","in":"query","required":false,"schema":{"enum":["created_at","status"],"type":"string","nullable":true}},{"name":"sort_dir","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SortDirection","nullable":true}},{"name":"project","in":"query","required":false,"schema":{"type":"string","nullable":true}},{"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":"query","required":false,"schema":{"enum":["Open","Allocated","Preempting","Terminated","Paused"],"type":"string","nullable":true}},{"name":"name","in":"query","required":false,"schema":{"type":"string","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/GetBidsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create Bid

> Place a new Spot bid

```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":{"CreateBidRequest":{"properties":{"project":{"type":"string","title":"Project"},"region":{"type":"string","title":"Region"},"instance_type":{"type":"string","title":"Instance Type"},"limit_price":{"type":"string","title":"Limit Price"},"instance_quantity":{"type":"integer","title":"Instance Quantity"},"name":{"type":"string","title":"Name"},"launch_specification":{"$ref":"#/components/schemas/LaunchSpecificationModel"}},"type":"object","required":["project","region","instance_type","limit_price","instance_quantity","name","launch_specification"],"title":"CreateBidRequest"},"LaunchSpecificationModel":{"properties":{"volumes":{"items":{"type":"string"},"type":"array","title":"Volumes","description":"List of volume FIDs"},"ssh_keys":{"items":{"type":"string"},"type":"array","title":"Ssh Keys","description":"List of SSH key FIDs"},"startup_script":{"type":"string","nullable":true},"kubernetes_cluster":{"type":"string","nullable":true},"image_version":{"type":"string","nullable":true},"memory_gb":{"type":"integer","nullable":true}},"type":"object","required":["volumes","ssh_keys"],"title":"LaunchSpecificationModel"},"BidModel":{"properties":{"fid":{"type":"string","title":"Fid"},"name":{"type":"string","title":"Name"},"project":{"type":"string","title":"Project"},"created_by":{"type":"string","title":"Created By"},"created_at":{"type":"string","format":"datetime","title":"Created At"},"deactivated_at":{"type":"string","format":"datetime","nullable":true},"limit_price":{"type":"string","title":"Limit Price"},"instance_quantity":{"type":"integer","title":"Instance Quantity"},"instance_type":{"type":"string","title":"Instance Type"},"region":{"type":"string","nullable":true},"instances":{"items":{"type":"string"},"type":"array","title":"Instances"},"launch_specification":{"$ref":"#/components/schemas/LaunchSpecificationModel"},"status":{"type":"string","enum":["Open","Allocated","Preempting","Terminated","Paused"],"title":"Status"}},"type":"object","required":["fid","name","project","created_by","created_at","limit_price","instance_quantity","instance_type","instances","launch_specification","status"],"title":"BidModel"},"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/spot/bids":{"post":{"tags":["spot"],"summary":"Create Bid","description":"Place a new Spot bid","operationId":"create_bid_v2_spot_bids_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBidRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BidModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get Bid

> Get a single Spot bid by FID

```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":{"BidModel":{"properties":{"fid":{"type":"string","title":"Fid"},"name":{"type":"string","title":"Name"},"project":{"type":"string","title":"Project"},"created_by":{"type":"string","title":"Created By"},"created_at":{"type":"string","format":"datetime","title":"Created At"},"deactivated_at":{"type":"string","format":"datetime","nullable":true},"limit_price":{"type":"string","title":"Limit Price"},"instance_quantity":{"type":"integer","title":"Instance Quantity"},"instance_type":{"type":"string","title":"Instance Type"},"region":{"type":"string","nullable":true},"instances":{"items":{"type":"string"},"type":"array","title":"Instances"},"launch_specification":{"$ref":"#/components/schemas/LaunchSpecificationModel"},"status":{"type":"string","enum":["Open","Allocated","Preempting","Terminated","Paused"],"title":"Status"}},"type":"object","required":["fid","name","project","created_by","created_at","limit_price","instance_quantity","instance_type","instances","launch_specification","status"],"title":"BidModel"},"LaunchSpecificationModel":{"properties":{"volumes":{"items":{"type":"string"},"type":"array","title":"Volumes","description":"List of volume FIDs"},"ssh_keys":{"items":{"type":"string"},"type":"array","title":"Ssh Keys","description":"List of SSH key FIDs"},"startup_script":{"type":"string","nullable":true},"kubernetes_cluster":{"type":"string","nullable":true},"image_version":{"type":"string","nullable":true},"memory_gb":{"type":"integer","nullable":true}},"type":"object","required":["volumes","ssh_keys"],"title":"LaunchSpecificationModel"},"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/spot/bids/{bid_fid}":{"get":{"tags":["spot"],"summary":"Get Bid","description":"Get a single Spot bid by FID","operationId":"get_bid_v2_spot_bids__bid_fid__get","parameters":[{"name":"bid_fid","in":"path","required":true,"schema":{"type":"string","title":"Bid Fid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BidModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Cancel Bid

> Cancel a Spot bid

```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":{"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/spot/bids/{bid_fid}":{"delete":{"tags":["spot"],"summary":"Cancel Bid","description":"Cancel a Spot bid","operationId":"cancel_bid_v2_spot_bids__bid_fid__delete","parameters":[{"name":"bid_fid","in":"path","required":true,"schema":{"type":"string","title":"Bid Fid"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Update Bid

> Update the limit price of a Spot bid

```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":{"UpdateBidRequest":{"properties":{"limit_price":{"type":"string","nullable":true},"paused":{"type":"boolean","nullable":true},"volumes":{"items":{"type":"string"},"type":"array","nullable":true},"memory_gb":{"type":"integer","nullable":true}},"type":"object","title":"UpdateBidRequest"},"BidModel":{"properties":{"fid":{"type":"string","title":"Fid"},"name":{"type":"string","title":"Name"},"project":{"type":"string","title":"Project"},"created_by":{"type":"string","title":"Created By"},"created_at":{"type":"string","format":"datetime","title":"Created At"},"deactivated_at":{"type":"string","format":"datetime","nullable":true},"limit_price":{"type":"string","title":"Limit Price"},"instance_quantity":{"type":"integer","title":"Instance Quantity"},"instance_type":{"type":"string","title":"Instance Type"},"region":{"type":"string","nullable":true},"instances":{"items":{"type":"string"},"type":"array","title":"Instances"},"launch_specification":{"$ref":"#/components/schemas/LaunchSpecificationModel"},"status":{"type":"string","enum":["Open","Allocated","Preempting","Terminated","Paused"],"title":"Status"}},"type":"object","required":["fid","name","project","created_by","created_at","limit_price","instance_quantity","instance_type","instances","launch_specification","status"],"title":"BidModel"},"LaunchSpecificationModel":{"properties":{"volumes":{"items":{"type":"string"},"type":"array","title":"Volumes","description":"List of volume FIDs"},"ssh_keys":{"items":{"type":"string"},"type":"array","title":"Ssh Keys","description":"List of SSH key FIDs"},"startup_script":{"type":"string","nullable":true},"kubernetes_cluster":{"type":"string","nullable":true},"image_version":{"type":"string","nullable":true},"memory_gb":{"type":"integer","nullable":true}},"type":"object","required":["volumes","ssh_keys"],"title":"LaunchSpecificationModel"},"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/spot/bids/{bid_fid}":{"patch":{"tags":["spot"],"summary":"Update Bid","description":"Update the limit price of a Spot bid","operationId":"update_bid_v2_spot_bids__bid_fid__patch","parameters":[{"name":"bid_fid","in":"path","required":true,"schema":{"type":"string","title":"Bid Fid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBidRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BidModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get Bid Status

> Get detailed status of a Spot bid.\
> \
> Returns a detailed status that includes instance-level status information.\
> The status can be one of: Open, Allocated, Preempting, Terminated,\
> Paused, Relocating.\
> \
> "Relocating" indicates that part of the order is being relocated.

```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":{"BidStatusResponse":{"properties":{"bid_fid":{"type":"string","title":"Bid Fid"},"status":{"type":"string","enum":["Open","Allocated","Preempting","Terminated","Paused","Relocating"],"title":"Status"}},"type":"object","required":["bid_fid","status"],"title":"BidStatusResponse","description":"Response model for the detailed bid 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/spot/bids/{bid_fid}/status":{"get":{"tags":["spot"],"summary":"Get Bid Status","description":"Get detailed status of a Spot bid.\n\nReturns a detailed status that includes instance-level status information.\nThe status can be one of: Open, Allocated, Preempting, Terminated,\nPaused, Relocating.\n\n\"Relocating\" indicates that part of the order is being relocated.","operationId":"get_bid_status_v2_spot_bids__bid_fid__status_get","parameters":[{"name":"bid_fid","in":"path","required":true,"schema":{"type":"string","title":"Bid Fid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BidStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get Bid History

> Get the history of events for a Spot bid.\
> \
> Returns a list of historical events including:\
> \- placing the bid\
> \- pausing the bid\
> \- resuming the bid\
> \- terminating the bid\
> \- changes to the limit price

```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":{"BidHistoryResponse":{"properties":{"bid_fid":{"type":"string","title":"Bid Fid"},"events":{"items":{"$ref":"#/components/schemas/BidHistoryEventModel"},"type":"array","title":"Events","description":"List of historical events for this bid, ordered by timestamp"}},"type":"object","required":["bid_fid","events"],"title":"BidHistoryResponse","description":"Response model for bid history."},"BidHistoryEventModel":{"properties":{"timestamp":{"type":"string","format":"datetime","title":"Timestamp","description":"When the event occurred"},"event_type":{"type":"string","enum":["Placed","Paused","Resumed","Terminated","Allocated","Preempted","Limit Price Changed","Memory Adjusted","Volumes Attached","Volumes Removed"],"title":"Event Type"},"limit_price":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"memory_gb":{"type":"integer","nullable":true},"persistent_disk_change":{"$ref":"#/components/schemas/PersistentDiskChange","nullable":true}},"type":"object","required":["timestamp","event_type"],"title":"BidHistoryEventModel","description":"A single event in the history of a spot bid."},"PersistentDiskChange":{"properties":{"attached":{"type":"string","nullable":true},"removed":{"type":"string","nullable":true}},"type":"object","title":"PersistentDiskChange"},"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/spot/bids/{bid_fid}/history":{"get":{"tags":["spot"],"summary":"Get Bid History","description":"Get the history of events for a Spot bid.\n\nReturns a list of historical events including:\n- placing the bid\n- pausing the bid\n- resuming the bid\n- terminating the bid\n- changes to the limit price","operationId":"get_bid_history_v2_spot_bids__bid_fid__history_get","parameters":[{"name":"bid_fid","in":"path","required":true,"schema":{"type":"string","title":"Bid Fid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BidHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get Auctions

> Get the Spot availability across all 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":{"AuctionModel":{"properties":{"fid":{"type":"string","title":"Fid"},"instance_type":{"type":"string","title":"Instance Type"},"region":{"type":"string","title":"Region"},"capacity":{"type":"integer","title":"Capacity"},"last_instance_price":{"type":"string","title":"Last Instance Price"},"lowest_allocated_price":{"type":"string","nullable":true},"adjustable_memory":{"type":"boolean","title":"Adjustable Memory"},"default_image_version":{"type":"string","nullable":true}},"type":"object","required":["fid","instance_type","region","capacity","last_instance_price","adjustable_memory"],"title":"AuctionModel"}}},"paths":{"/v2/spot/availability":{"get":{"tags":["spot"],"summary":"Get Auctions","description":"Get the Spot availability across all regions.","operationId":"get_auctions_v2_spot_availability_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/AuctionModel"},"type":"array","title":"Response Get Auctions V2 Spot Availability Get"}}}}}}}}}
```


---

# 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/spot.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.