Ofertas
Una oferta es un bloque alquilable de una máquina: 1, 2, 4 u 8 GPUs, con un precio para el bloque completo. Estos endpoints son la base sobre la que está construida la página Alquilar GPU. Consulte Ofertas y bloques para el concepto.
Listar ofertas
curl -s "$SUPERHEAT_API/v1/offers?gpu_model=H100%20SXM&num_gpus=2&sort=price_asc&limit=50" \
-H "Authorization: Bearer $SUPERHEAT_KEY"
GET /v1/offers devuelve {"items": [...], "next_cursor": ...}. El filtrado, el ordenamiento y la paginación se hacen en el servidor. Sin parámetros de consulta obtiene todas las ofertas disponibles, de la más barata a la más cara, hasta el tope sin paginar que se describe en Paginación.
Filtros
| Parámetro | Tipo | Predeterminado | Coincide con |
|---|---|---|---|
gpu_model | cadena | ninguno | Modelo exacto de GPU, por ejemplo H100 SXM o H200 SXM. Distingue mayúsculas y espacios. |
gpu_family | cadena | ninguno | Una familia de arquitectura: Hopper, Ampere, Ada, Blackwell u Other. La familia se deduce en el servidor a partir del nombre de modelo normalizado, así que un nombre en bruto como NVIDIA GeForce RTX 4090 cuenta como Ada. Las familias que hay ahora en el catálogo, con sus recuentos, están en el resumen del catálogo. Una familia sin nada publicado devuelve una página vacía, no un error |
q | cadena, hasta 100 caracteres | ninguno | Búsqueda de texto libre: una subcadena, sin distinguir mayúsculas, del modelo de GPU, el nombre de host y la región tomados juntos. % y _ se buscan literalmente, no como comodines |
num_gpus | entero | ninguno | Tamaño del bloque: 1, 2, 4 u 8 |
region | cadena | ninguno | Un código de región como US-CA, o un código de país como US |
min_vram_gb | entero | ninguno | Ofertas con al menos esta cantidad de VRAM por GPU |
max_price_per_hour_micro | entero | ninguno | Ofertas con este precio por hora o menos para el bloque completo, en millonésimas de dólar: $3.00 son 3000000 |
include_rented | booleano | false | Con true, las ofertas agotadas (available_units igual a 0) se devuelven junto a las que tienen unidades libres. Las ofertas retiradas nunca se devuelven |
sort | enum | price_asc | Vea más abajo |
limit | entero, de 1 a 200 | ninguno | Tamaño de página. Vea Paginación |
cursor | cadena | ninguno | El next_cursor de la página anterior |
Los filtros se combinan con AND. Un valor de sort desconocido, un limit fuera de 1 a 200 o un número demasiado grande para su campo se rechazan con 422.
Valores de ordenamiento
| Valor | Ordena por |
|---|---|
price_asc | Precio por hora del bloque, de menor a mayor |
price_desc | Precio por hora del bloque, de mayor a menor |
tflops_desc | Rendimiento del bloque, de mayor a menor. Las ofertas sin cifra de TFLOPS van al final |
vram_desc | VRAM por GPU, de mayor a menor |
Las ofertas que empatan en el valor de ordenamiento se ordenan por su id, así que el orden es estable de una petición a otra.
Paginación
Pase limit para paginar. Cada respuesta trae next_cursor; envíelo de vuelta como cursor, con el mismo sort, para obtener la página siguiente. En la última página next_cursor es null.
curl -s "$SUPERHEAT_API/v1/offers?sort=price_asc&limit=100&cursor=$NEXT_CURSOR" \
-H "Authorization: Bearer $SUPERHEAT_KEY"
- El cursor es una posición en el orden, no una instantánea: guarda el valor de ordenamiento y el id de la última oferta. Una oferta publicada mientras usted pagina cae donde le corresponde y nunca desplaza las páginas siguientes. Los filtros pueden cambiar entre páginas.
- Un cursor solo sirve con el ordenamiento del que salió. Un cursor de otro ordenamiento, o uno editado, se rechaza con
422 INVALID_CURSOR. Empiece de nuevo sin cursor. - Las ofertas sin cifra de TFLOPS se quedan al final de un recorrido
tflops_desc, a través de las páginas.
Una petición sin limit devuelve todo el catálogo que coincide, como siempre, hasta 1.000 ofertas. Por encima de eso devuelve las primeras 1.000, un next_cursor y la cabecera de respuesta X-Result-Truncated: true, para que un script que no pagina sepa que su lista está incompleta. Pagine con limit si alguna vez puede leer más de 1.000 ofertas.
Campos de la respuesta
| Campo | Tipo | Significado |
|---|---|---|
id | uuid | Páselo como offer_id al desplegar |
gpu_model | cadena | Modelo de GPU del bloque |
num_gpus | entero | GPUs que hay en el bloque |
available_units | entero | Cuántas unidades de esta forma puede servir la máquina ahora mismo. 0 significa agotada, no retirada |
capacity_units | entero | El techo: cuántas podría servir si la máquina estuviera inactiva |
vram_gb | entero | VRAM por GPU |
tflops | float | Rendimiento del bloque completo |
cuda_version | cadena | Versión de CUDA que ofrece el host |
vm_capable | booleano | Si aquí pueden ejecutarse plantillas con modo de lanzamiento vm |
disk_quota_capable | booleano | Si el host impone una cuota de disco por instancia. Véase más abajo |
price_per_hour_micro | entero | Precio del bloque completo, por hora |
storage_price_per_gb_hour_micro | entero | Precio del disco, por GB y por hora |
max_duration_hours | entero o null | Límite de tiempo de alquiler, cuando la oferta tiene uno |
status | cadena | Siempre available en todo lo que devuelve la API. Véase más abajo |
machine | objeto | El host sobre el que está el bloque |
status es listada frente a retirada, no libre frente a tomada. El único otro valor es inactive, que significa que la oferta está retirada —la máquina ya no está, su modelo de GPU cambió, o ninguna regla de precios le aplica ya— y las ofertas retiradas se filtran del listado y responden 404 en el endpoint de detalle. Agotada es available_units en 0. No existe un estado rented: una máquina de 2 GPU vende su forma 1x dos veces, así que una misma forma puede estar alquilada y disponible al mismo tiempo.
disk_quota_capable dice si la máquina puede sujetarlo al disk_gb que pidió. Se le factura esa cifra en cualquier caso. Es true únicamente donde el host ha puesto el almacenamiento de Docker sobre XFS con cuotas de proyecto, que es un paso opcional del dueño de la máquina, así que espere que false sea habitual. En una máquina false, todos los que alquilan ese equipo comparten un volumen y un co-inquilino que escriba más de lo que compró puede llenarlo por debajo de usted; disk_gb es un tope que vendió el catálogo, no una porción reservada para usted. En una máquina true es una cuota impuesta por instancia. La consola lo muestra como garantizado frente a compartido en la tarjeta de la oferta.
El objeto machine lleva hostname, region, country_code, cpu_model, cpu_cores, ram_gb, disk_type, disk_gb, net_up_mbps, net_down_mbps, pcie_gen, pcie_width, reliability, verified y next_maintenance.
machine.disk_gb es el volumen entero, y es una cota superior del disk_gb que pida al desplegar, no la promesa de que pueda obtenerlo: 50 GB quedan reservados para el propio host, y todo lo ya comprometido por otros arrendatarios de esa máquina se descuenta del resto. Pedir más de lo que queda devuelve 409 MACHINE_DISK_EXHAUSTED con la cifra que sí estaba disponible.
machine.reliability es null cuando nunca se ha medido nada para ese host, que no es la misma afirmación que 0.0. machine.next_maintenance es cuándo el host ha programado que la máquina se caiga, o null. Es el inicio de la ventana más próxima aún por llegar o todavía en curso, así que puede estar en el pasado. Trátelo como un aviso y no como una garantía: el host puede reservar una ventana un minuto después de que usted alquile el equipo, y una ventana a menos de unos 75 minutos hace que un despliegue falle con 409 MACHINE_IN_MAINTENANCE.
Los precios los fija Superheat, no los dueños de las máquinas, y el precio de la oferta queda congelado en la instancia cuando la alquila. Un cambio de precio posterior en el catálogo no mueve la tarifa que está pagando.
Resumen del catálogo
curl -s "$SUPERHEAT_API/v1/offers/summary" \
-H "Authorization: Bearer $SUPERHEAT_KEY"
GET /v1/offers/summary cuenta todo el catálogo publicado, no una página filtrada. El mercado lo usa para sus opciones de filtro y su titular.
| Campo | Significado |
|---|---|
offers | Ofertas publicadas, incluidas las agotadas |
available_offers | Ofertas con al menos una unidad libre ahora mismo |
machines | Máquinas distintas que publican al menos una oferta |
available_gpus | GPUs libres. Por cada máquina cuenta su bloque libre más grande, nunca la suma de sus tamaños de bloque: una máquina de 8 GPUs publica sus formas 1×, 2×, 4× y 8× sobre las mismas tarjetas |
min_price_per_hour_micro, max_price_per_hour_micro | El precio de bloque más barato y el más caro, o null cuando no hay nada publicado |
models | Una entrada por modelo de GPU: gpu_model, gpu_family, offers, available_offers, machines, available_gpus y su rango de precios |
families | Una entrada por gpu_family, con offers y available_offers. Other va al final. Son los valores que acepta gpu_family |
regions | Una entrada por country_code, con offers y available_offers. Son los valores que acepta region |
generated_at | Cuándo se tomaron los recuentos |
source | snapshot o live, vea más abajo |
Los recuentos salen de una instantánea que se reconstruye después de cada actualización del catálogo (source: snapshot), así que pueden ir hasta una actualización por detrás de un despliegue. Cuando no hay una instantánea reciente —ninguna de los últimos cinco minutos, o de los últimos tres intervalos de actualización si estos son más largos, porque la actualización está desactivada o falló la reconstrucción de la instantánea— el endpoint cuenta el catálogo para esa petición y lo indica con source: live. El endpoint de listado siempre es en vivo. Use el resumen para opciones y cifras de titular, y vuelva a leer available_units en la oferta antes de desplegar.
Obtener una sola oferta
curl -s "$SUPERHEAT_API/v1/offers/5d2f9c31-8b64-4c0e-9a77-2e0f1b6a4c11" \
-H "Authorization: Bearer $SUPERHEAT_KEY"
Devuelve una sola oferta con la forma anterior, esté agotada o no. Las ofertas desconocidas y las retiradas devuelven 404 OFFER_NOT_FOUND.
Vuelva a leer available_units antes de desplegar, no status. La última unidad libre puede ser tomada entre su llamada de listado y su llamada de creación, y POST /v1/instances responderá 409 OFFER_UNAVAILABLE.
Actualidad del catálogo
curl -s "$SUPERHEAT_API/v1/catalog/status" \
-H "Authorization: Bearer $SUPERHEAT_KEY"
{
"last_synced_at": "2026-07-24T11:04:12.907Z",
"last_error": null,
"sync_enabled": true,
"unpriced_gpu_models": []
}
| Campo | Tipo | Significado |
|---|---|---|
last_synced_at | timestamp o null | Cuándo se actualizó correctamente el catálogo por última vez |
last_error | cadena o null | El último fallo de actualización, si lo hubo |
sync_enabled | booleano | Si el catálogo se actualiza automáticamente o no |
unpriced_gpu_models | arreglo de cadenas | Modelos de GPU que la última actualización retuvo porque Superheat no tiene precio para ellos |
Una actualización fallida deja en su lugar el catálogo anterior en vez de vaciarlo, así que un last_synced_at antiguo significa que las ofertas que está leyendo quizá ya no se puedan alquilar. En ese caso el mercado muestra un aviso de desactualización; en un script, tome una marca de tiempo antigua como motivo para esperar 409 OFFER_UNAVAILABLE y reintentar con la siguiente oferta.
Un modelo que está en unpriced_gpu_models no produce ninguna oferta, en lugar de una oferta a un precio inventado, así que desde /v1/offers a secas ese hardware es indistinguible del hardware que nadie está alojando. Este campo es la única forma de diferenciarlos: si el modelo que busca aparece aquí, la capacidad existe y todavía no se puede alquilar, y sondear /v1/offers para él no va a funcionar nunca.