Reservations

Get Reservation Instance Types

get

Get instance types available for reservation.

Returns the subset of public instance types that are currently eligible for reservation. Instance types can be disabled for reservation via the Unleash reservation-disabled-instance-types feature flag.

Authorizations

MithrilAPIKey

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Successful Response

application/json

fidstringRequiredExample: it_abc123456

namestringRequiredExample: h100.80gb.sxm

num_cpusintegerRequiredExample: 192

cpu_typestringRequiredExample: Intel

ram_gbintegerRequiredExample: 1800

num_gpusintegerRequiredExample: 8

gpu_typestringRequiredExample: H100

gpu_memory_gbintegerRequiredExample: 80

gpu_socketstringRequiredExample: SXM5

local_storage_gbintegerRequiredExample: 7800

network_typestring · nullableOptionalExample: InfiniBand

ib_countintegerRequiredExample: 8

bridge_countintegerRequiredExample: 4

hourly_pricenumberRequiredExample: 0.12

get/v2/reservation/instance-types

HTTPcURLJavaScriptPython

GET /v2/reservation/instance-types HTTP/1.1
Host: api.mithril.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Successful Response

[
  {
    "fid": "it_abc123456",
    "name": "h100.80gb.sxm",
    "num_cpus": 192,
    "cpu_type": "Intel",
    "ram_gb": 1800,
    "num_gpus": 8,
    "gpu_type": "H100",
    "gpu_memory_gb": 80,
    "gpu_socket": "SXM5",
    "local_storage_gb": 7800,
    "network_type": "InfiniBand",
    "ib_count": 8,
    "bridge_count": 4,
    "hourly_price": 0.12
  }
]

Get Reservation Quote

get

Get pricing offers for a reservation.

Reservation offers are dynamic and the price may change slightly since the time it was generated. You can include an optional "max_unit_price" (which you can set at the quoted price or slightly above it) to ensure your reservation request fails if the new price is above that max.

Authorizations

MithrilAPIKey

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

projectstringRequiredExample: proj_abc123456

instance_typestringRequiredExample: it_abc123456

regionstringRequiredExample: us-central1-a

start_timestring · datetimeRequiredExample: 2024-01-01T00:00:00Z

end_timestring · datetimeRequiredExample: 2024-01-01T00:00:00Z

quantityinteger · min: 1Required

Responses

200

Successful Response

application/json

Response with all pricing offers available when creating a new reservation.

422

Validation Error

application/json

get/v2/reservation/quote

HTTPcURLJavaScriptPython

GET /v2/reservation/quote?project=proj_abc123456&instance_type=it_abc123456&region=us-central1-a&start_time=2024-01-01T00%3A00%3A00Z&end_time=2024-01-01T00%3A00%3A00Z&quantity=1 HTTP/1.1
Host: api.mithril.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "offers": [
    {
      "key": "text",
      "display_name": "text",
      "unit_price": "text",
      "return_buyback_price": "text",
      "pause_buyback_price": "text",
      "total_price": "text",
      "total_etbp_value": "text",
      "total_fubp_value": "text",
      "option_premium": "text"
    }
  ]
}

Get Availability

get

Get availability information for reservations.

This endpoint supports three different modes for querying availability:

Mode: latest_end_time (default)

Get the latest possible end time for a reservation given a start time and quantity.

Required parameters:

• start_time: Desired start time for the reservation
• quantity: Number of instances needed
• project: Project FID
• instance_type: Instance type FID
• region: Region name

Returns: Latest possible end time and availability status

Example:

GET /reservation/availability?
    start_time=2024-01-01T00:00:00Z&
    quantity=4&
    project=proj_01h8x2k9m3n4p5q6r7s8t9u0v&
    instance_type=it_01h8x2k9m3n4p5q6r7s8t9u0v&
    region=us-central1-a

Mode: slots

Get all available slots in a time range.

Required parameters:

• earliest_start_time: Start of the time range to search
• latest_end_time: End of the time range to search
• project: Project FID
• instance_type: Instance type FID
• region: Region name

Returns: List of available time slots with quantities

Example:

GET /reservation/availability?
    mode=slots&
    earliest_start_time=2024-01-01T00:00:00Z&
    latest_end_time=2024-01-02T00:00:00Z&
    project=proj_01h8x2k9m3n4p5q6r7s8t9u0v&
    instance_type=it_01h8x2k9m3n4p5q6r7s8t9u0v&
    region=us-central1-a

Mode: check

Check if a specific time slot is available for reservation.

Required parameters:

• start_time: Start of the desired time slot
• end_time: End of the desired time slot
• quantity: Number of instances needed
• project: Project FID
• instance_type: Instance type FID
• region: Region name

Returns: Boolean indicating if the slot is available

Example:

GET /reservation/availability?
    mode=check&
    start_time=2024-01-01T00:00:00Z&
    end_time=2024-01-01T12:00:00Z&
    quantity=4&
    project=proj_01h8x2k9m3n4p5q6r7s8t9u0v&
    instance_type=it_01h8x2k9m3n4p5q6r7s8t9u0v&
    region=us-central1-a

Common Parameters

All modes require these parameters:

• project: Project FID
• instance_type: Instance type FID
• region: Region name

Authentication

Requires authentication and user must be a member of the specified project.

Authorizations

MithrilAPIKey

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

projectstringRequired

instance_typestringRequired

regionstringRequired

modestring · enumOptionalDefault: latest_end_timePossible values:

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

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

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

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

quantityinteger · nullableOptional

Responses

200

Successful Response

application/json

start_timestring · datetimeRequiredExample: 2024-01-01T00:00:00Z

end_timestring · datetimeRequiredExample: 2024-01-01T00:00:00Z

quantityintegerRequired

422

Validation Error

application/json

get/v2/reservation/availability

HTTPcURLJavaScriptPython

GET /v2/reservation/availability?project=text&instance_type=text&region=text HTTP/1.1
Host: api.mithril.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-01-01T00:00:00Z",
    "quantity": 1
  }
]

Get Reservations

get

Get all reservations for a project

Authorizations

MithrilAPIKey

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

statusstring · enum · nullableOptionalPossible values:

limitinteger · min: 1 · max: 100 · nullableOptional

Responses

200

Successful Response

application/json

next_cursorstring · nullableOptional

422

Validation Error

application/json

get/v2/reservation

HTTPcURLJavaScriptPython

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

{
  "data": [
    {
      "fid": "res_abc123456",
      "name": "text",
      "project": "proj_abc123456",
      "created_by": "user_abc123456",
      "created_at": "2024-01-01T00:00:00Z",
      "deactivated_at": "2024-01-01T00:00:00Z",
      "instance_quantity": 4,
      "instance_type": "it_abc123456",
      "region": "us-central1-a",
      "instances": [
        "inst_abc123456"
      ],
      "launch_specification": {
        "volumes": [
          "vol_1234567890",
          "vol_1234567891"
        ],
        "ssh_keys": [
          "sshkey_1234567890",
          "sshkey_1234567891"
        ],
        "startup_script": "text",
        "kubernetes_cluster": "clust_abc123456",
        "image_version": "imgver_abc123456",
        "memory_gb": 1
      },
      "status": "Pending",
      "start_time": "2024-01-01T00:00:00Z",
      "end_time": "2024-01-01T00:00:00Z",
      "total_price": "$47.76",
      "unit_price": "$1.99"
    }
  ],
  "next_cursor": "text"
}

Create Reservation

post

Create a new reservation.

Authorizations

MithrilAPIKey

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

projectstringRequiredExample: proj_abc123456

instance_typestringRequiredExample: it_abc123456

regionstringRequiredExample: us-central1-a

start_timestring · datetimeRequiredExample: 2024-01-01T00:00:00Z

end_timestring · datetimeRequiredExample: 2024-01-01T00:00:00Z

instance_quantityintegerRequiredExample: 4

namestringRequired

notification_emailstring · nullableOptional

Responses

201

Successful Response

application/json

fidstringRequiredExample: res_abc123456

namestringRequired

projectstringRequiredExample: proj_abc123456

created_bystringRequiredExample: user_abc123456

created_atstring · datetimeRequiredExample: 2024-01-01T00:00:00Z

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

instance_quantityintegerRequiredExample: 4

instance_typestringRequiredExample: it_abc123456

regionstring · nullableOptionalExample: us-central1-a

instancesstring[]Required

statusstring · enumRequiredExample: PendingPossible values:

start_timestring · datetimeRequiredExample: 2024-01-01T00:00:00Z

end_timestring · datetimeRequiredExample: 2024-01-01T00:00:00Z

total_pricestringRequiredExample: $47.76

unit_pricestringRequiredExample: $1.99

422

Validation Error

application/json

post/v2/reservation

HTTPcURLJavaScriptPython

POST /v2/reservation HTTP/1.1
Host: api.mithril.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 522

{
  "project": "proj_abc123456",
  "instance_type": "it_abc123456",
  "region": "us-central1-a",
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-01T00:00:00Z",
  "instance_quantity": 4,
  "name": "text",
  "launch_specification": {
    "volumes": [
      "vol_1234567890",
      "vol_1234567891"
    ],
    "ssh_keys": [
      "sshkey_1234567890",
      "sshkey_1234567891"
    ],
    "startup_script": "text",
    "kubernetes_cluster": "clust_abc123456",
    "image_version": "imgver_abc123456",
    "memory_gb": 1
  },
  "price_specification": {
    "offer_key": "standard",
    "max_unit_price": 500
  },
  "notification_email": "text"
}

{
  "fid": "res_abc123456",
  "name": "text",
  "project": "proj_abc123456",
  "created_by": "user_abc123456",
  "created_at": "2024-01-01T00:00:00Z",
  "deactivated_at": "2024-01-01T00:00:00Z",
  "instance_quantity": 4,
  "instance_type": "it_abc123456",
  "region": "us-central1-a",
  "instances": [
    "inst_abc123456"
  ],
  "launch_specification": {
    "volumes": [
      "vol_1234567890",
      "vol_1234567891"
    ],
    "ssh_keys": [
      "sshkey_1234567890",
      "sshkey_1234567891"
    ],
    "startup_script": "text",
    "kubernetes_cluster": "clust_abc123456",
    "image_version": "imgver_abc123456",
    "memory_gb": 1
  },
  "status": "Pending",
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-01T00:00:00Z",
  "total_price": "$47.76",
  "unit_price": "$1.99"
}

Get Extension Availability

get

Get extension availability for a reservation

Authorizations

MithrilAPIKey

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

reservation_fidstringRequiredExample: res_abc123456

Responses

200

Successful Response

application/json

latest_extension_timestring · datetimeRequiredExample: 2024-01-01T00:00:00Z

availablebooleanRequired

422

Validation Error

application/json

get/v2/reservation/{reservation_fid}/extension-availability

HTTPcURLJavaScriptPython

GET /v2/reservation/{reservation_fid}/extension-availability HTTP/1.1
Host: api.mithril.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "latest_extension_time": "2024-01-01T00:00:00Z",
  "available": true
}

Extend Reservation

post

Extend a reservation to the requested time.

Authorizations

MithrilAPIKey

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

reservation_fidstringRequiredExample: res_abc123456

Body

application/json

end_timestring · datetimeRequiredExample: 2024-01-01T00:00:00Z

Responses

200

Successful Response

application/json

fidstringRequiredExample: res_abc123456

namestringRequired

projectstringRequiredExample: proj_abc123456

created_bystringRequiredExample: user_abc123456

created_atstring · datetimeRequiredExample: 2024-01-01T00:00:00Z

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

instance_quantityintegerRequiredExample: 4

instance_typestringRequiredExample: it_abc123456

regionstring · nullableOptionalExample: us-central1-a

instancesstring[]Required

statusstring · enumRequiredExample: PendingPossible values:

start_timestring · datetimeRequiredExample: 2024-01-01T00:00:00Z

end_timestring · datetimeRequiredExample: 2024-01-01T00:00:00Z

total_pricestringRequiredExample: $47.76

unit_pricestringRequiredExample: $1.99

422

Validation Error

application/json

post/v2/reservation/{reservation_fid}/extend

HTTPcURLJavaScriptPython

POST /v2/reservation/{reservation_fid}/extend HTTP/1.1
Host: api.mithril.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 103

{
  "end_time": "2024-01-01T00:00:00Z",
  "price_specification": {
    "offer_key": "standard",
    "max_unit_price": 500
  }
}

{
  "fid": "res_abc123456",
  "name": "text",
  "project": "proj_abc123456",
  "created_by": "user_abc123456",
  "created_at": "2024-01-01T00:00:00Z",
  "deactivated_at": "2024-01-01T00:00:00Z",
  "instance_quantity": 4,
  "instance_type": "it_abc123456",
  "region": "us-central1-a",
  "instances": [
    "inst_abc123456"
  ],
  "launch_specification": {
    "volumes": [
      "vol_1234567890",
      "vol_1234567891"
    ],
    "ssh_keys": [
      "sshkey_1234567890",
      "sshkey_1234567891"
    ],
    "startup_script": "text",
    "kubernetes_cluster": "clust_abc123456",
    "image_version": "imgver_abc123456",
    "memory_gb": 1
  },
  "status": "Pending",
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-01T00:00:00Z",
  "total_price": "$47.76",
  "unit_price": "$1.99"
}

Update Reservation

patch

Update a reservation's pause/resume status and/or volumes

Authorizations

MithrilAPIKey

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

reservation_fidstringRequiredExample: res_abc123456

Body

application/json

pausedboolean · nullableOptional

volumesstring[] · nullableOptional

Responses

200

Successful Response

application/json

fidstringRequiredExample: res_abc123456

namestringRequired

projectstringRequiredExample: proj_abc123456

created_bystringRequiredExample: user_abc123456

created_atstring · datetimeRequiredExample: 2024-01-01T00:00:00Z

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

instance_quantityintegerRequiredExample: 4

instance_typestringRequiredExample: it_abc123456

regionstring · nullableOptionalExample: us-central1-a

instancesstring[]Required

statusstring · enumRequiredExample: PendingPossible values:

start_timestring · datetimeRequiredExample: 2024-01-01T00:00:00Z

end_timestring · datetimeRequiredExample: 2024-01-01T00:00:00Z

total_pricestringRequiredExample: $47.76

unit_pricestringRequiredExample: $1.99

422

Validation Error

application/json

patch/v2/reservation/{reservation_fid}

HTTPcURLJavaScriptPython

PATCH /v2/reservation/{reservation_fid} HTTP/1.1
Host: api.mithril.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 43

{
  "paused": true,
  "volumes": [
    "vol_abc123456"
  ]
}

{
  "fid": "res_abc123456",
  "name": "text",
  "project": "proj_abc123456",
  "created_by": "user_abc123456",
  "created_at": "2024-01-01T00:00:00Z",
  "deactivated_at": "2024-01-01T00:00:00Z",
  "instance_quantity": 4,
  "instance_type": "it_abc123456",
  "region": "us-central1-a",
  "instances": [
    "inst_abc123456"
  ],
  "launch_specification": {
    "volumes": [
      "vol_1234567890",
      "vol_1234567891"
    ],
    "ssh_keys": [
      "sshkey_1234567890",
      "sshkey_1234567891"
    ],
    "startup_script": "text",
    "kubernetes_cluster": "clust_abc123456",
    "image_version": "imgver_abc123456",
    "memory_gb": 1
  },
  "status": "Pending",
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-01T00:00:00Z",
  "total_price": "$47.76",
  "unit_price": "$1.99"
}

Terminate Instance

post

Remove and permanently delete instances from this reservation.

You will receive a credit based on your early termination buyback price associated with this reservation and the time remaining in the reservation.

This endpoint does a best effort to termiante all instances, but it can fail to do so for some instances. If you receive a 207, then please see the response for details.

Authorizations

MithrilAPIKey

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

reservation_fidstringRequiredExample: res_abc123456

Body

application/json

instancesstring[] · min: 1Required

reduce_capacityconst: Required

Responses

200

Successfully terminated all instances.

application/json

anyOptional

207

Failed to terminate some instances. See response for details.

application/json

400

The reservation was already ended.

404

Either the reservation or one of the instances could not be found.

422

Validation Error

application/json

502

No instance was able to be stopped due to an internal error.

post/v2/reservation/{reservation_fid}/terminate-instances

HTTPcURLJavaScriptPython

POST /v2/reservation/{reservation_fid}/terminate-instances HTTP/1.1
Host: api.mithril.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 55

{
  "instances": [
    "inst_abc123456"
  ],
  "reduce_capacity": true
}

No content

Get Reservation History

get

Get the activity history for a reservation.

Returns a chronological list of order-level status changes (Placed, Active, Paused, Resumed, Canceled, Ended) interleaved with aggregated instance-level status events (instances running, stopped, error) bucketed into 60-second windows so burst transitions appear as a single entry.

Authorizations

MithrilAPIKey

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

reservation_fidstringRequiredExample: res_abc123456

Responses

200

Successful Response

application/json

Response model for reservation history.

reservation_fidstringRequiredExample: res_abc123456

422

Validation Error

application/json

get/v2/reservation/{reservation_fid}/history

HTTPcURLJavaScriptPython

GET /v2/reservation/{reservation_fid}/history HTTP/1.1
Host: api.mithril.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "reservation_fid": "res_abc123456",
  "events": [
    {
      "timestamp": "2024-01-01T00:00:00Z",
      "event_type": "Placed",
      "user_id": "text",
      "unit_price_cents": 1,
      "pause_credit_cents": 1,
      "return_credit_cents": 1
    }
  ]
}

Get Reservation Usage

get

Get usage breakdown for a flex reservation.

Authorizations

MithrilAPIKey

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

reservation_fidstringRequiredExample: res_abc123456

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get/v2/reservation/{reservation_fid}/usage

HTTPcURLJavaScriptPython

GET /v2/reservation/{reservation_fid}/usage HTTP/1.1
Host: api.mithril.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "reservation": {
    "fid": "res_abc123456",
    "order_name": "text",
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2024-01-01T00:00:00Z",
    "status": "Open",
    "committed_cost_cents": 1
  },
  "summary": {
    "committed_cost_cents": 1,
    "flex_use_credits_cents": 1,
    "early_termination_credits_cents": 1,
    "net_cost_cents": 1,
    "reserved_instance_hours": "text",
    "active_instance_hours": "text",
    "idle_instance_hours": "text",
    "as_of": "2024-01-01T00:00:00Z"
  },
  "grants": [
    {
      "fid": "text",
      "starts_at": "2024-01-01T00:00:00Z",
      "ends_at": "2024-01-01T00:00:00Z",
      "quantity": 1,
      "unit_price": 1,
      "price_credit": 1,
      "return_credit": 1
    }
  ],
  "pricing_events": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "occurred_at": "2024-01-01T00:00:00Z",
      "instance_fid": "inst_abc123456",
      "instance_name": "text",
      "instance_status": "STATUS_NEW"
    }
  ],
  "reservation_events": [
    {
      "occurred_at": "2024-01-01T00:00:00Z",
      "event_type": "Started",
      "reservation_name": "text"
    }
  ]
}