Referencia de la API

Gasto en IA

Gasto en modelos de IA por facturador, proveedor del modelo, modelo y medidor, frente a tus órdenes de compra.

Más sobre este recurso

Nuevo con los controles de gasto en IA. El gasto en IA es lo que cuestan las líneas de servicios de IA de la facturación de AWS, Google Cloud, Azure y OCI que tienes conectada (Amazon Bedrock, SageMaker, Vertex AI, Azure OpenAI, OCI Generative AI y los modelos del marketplace en la misma factura), más lo que informan los proveedores de IA que conectas directamente (consulta Proveedores de IA). Pleaxy las lee a través de la misma conexión de solo lectura que el resto de la factura, con la misma elección de fuentes de datos: una conexión que permite current_cost da el mes en curso y una previsión; una que permite invoices, el mes cerrado. AWS es la excepción: da las líneas de IA solo a través de Cost Explorer, así que una conexión de AWS necesita current_cost para cualquier cifra de IA (con él, llega también el mes cerrado). El proveedor es quien factura (el facturador); la empresa cuyo modelo se usó es el vendor de la línea, así que Claude en Bedrock es gasto de AWS con vendor anthropic, y nada se cuenta dos veces. Todos los importes están en la moneda de facturación del facturador, nunca convertidos ni sumados entre monedas. Las reglas de atribución asignan las etiquetas, los proyectos y los espacios de trabajo de los proveedores a centros de coste (GetAiAttribution), y una línea de orden aprobada puede fijar el propio tope de gasto del proveedor (SetAiSpendLimit, opcional).

Obtener gasto en IA

Gasto en IA de un periodo, por facturador, proveedor del modelo, modelo o centro de coste.

GET/v1/workspaces/{regionId}/ai-spend

Parámetros

  • periodstring

    El mes, YYYY-MM. Por defecto, el mes en curso.

  • groupBy"invoicer" | "vendor" | "model" | "costCenter"

    Qué es cada grupo. Por defecto invoicer, que coincide con tus facturas. vendor suma un proveedor de modelos entre facturadores (lo que gastas en Claude, lo facture quien lo facture), model un id de modelo tal como se factura, costCenter los centros de coste de las reglas de atribución.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Para un periodo (por defecto, el mes en curso), el gasto en IA de cada facturador conectado, agrupado según groupBy: mes en curso, previsión para todo el periodo, último mes cerrado y variación frente a él, con el consumo por medidor y, junto a cada facturador, las líneas de orden de compra abiertas emitidas a su nombre y lo que les queda. Las cifras son las líneas de IA que sincronizaron las conexiones (a diario para current_cost, como el coste del mes en curso hoy). Un facturador cuya conexión solo lee facturas muestra el mes cerrado: su mes en curso y su previsión no aparecen (una cuenta de AWS que solo lee facturas no tiene líneas de IA y figura en notReadable). La previsión es la del proveedor cuando la ofrece (AWS Cost Explorer); si no, lineal sobre los días transcurridos. Los importes están en la moneda de facturación de cada facturador, y los totales son una entrada por moneda, nunca sumados entre monedas. Agrupar por costCenter sigue las reglas de atribución (GetAiAttribution); una línea con la que no coincide ninguna regla queda sin atribuir.

Campos de la respuesta

  • periodstring

    El mes al que corresponden las cifras, YYYY-MM.

  • asOfstring

    Cuándo se sincronizó la línea más reciente, ISO 8601. El mes en curso es a esa fecha, no a ahora.

  • totalsArray<object>

    Una entrada por moneda de facturación, nunca sumadas entre monedas: monthToDate, forecast para todo el periodo, lastMonth (el último mes cerrado) y changePct, la variación de la previsión frente a lastMonth en porcentaje.

  • groups[].keystring

    Según groupBy: el id de la conexión de nube del facturador; el proveedor del modelo (anthropic, openai, google, meta, mistral, amazon, microsoft, cohere, xai, deepseek o unknown para un tipo de uso que Pleaxy aún no ha mapeado); el id del modelo tal como se factura, p. ej. claude-sonnet-4-5 o gemini-2.5-pro; o el código del centro de coste.

  • groups[].labelstring

    Qué mostrar para el grupo: la etiqueta de cuenta de la conexión, el nombre del proveedor del modelo, el nombre del modelo o el nombre del centro de coste.

  • groups[].invoicerstring

    Quién factura el gasto del grupo, una nube o un proveedor de IA, con invoicerId como su conexión: siempre con groupBy invoicer y, para un grupo por proveedor de modelo o por modelo, cuando una sola conexión lo factura todo (Claude solo a través de Bedrock, por ejemplo); ausente cuando son varias. Un grupo por centro de coste nunca lo tiene.

  • groups[].monthToDatenumber

    En la moneda del grupo, con forecast, lastMonth y changePct como en totals. monthToDate y forecast no aparecen para un facturador cuya conexión solo lee facturas: muestra solo lastMonth.

  • groups[].quantitiesArray<object>

    El consumo por medidor. Líneas medidas en tokens: input_tokens, output_tokens, cached_input_tokens, cache_write_tokens, batch_input_tokens, batch_output_tokens, images, audio_seconds, embeddings_tokens o requests. Líneas de capacidad: gpu_hours, ptu_hours, model_units_hours o cluster_hours. other para una línea que Pleaxy aún no ha mapeado a un medidor. unit es la unidad de la cantidad: 1M_tokens, tokens, requests, images, seconds, gpu_hours, ptu_hours, model_unit_hours o units para una línea sin mapear.

  • groups[].purchaseOrdersArray<object>

    Las líneas de orden de compra abiertas emitidas al facturador del grupo, con lo que queda en cada una (remaining, en la moneda del grupo) tras las facturas ya cargadas contra ella. Solo para un grupo con facturador.

  • groups[].servicesArray<object>

    Solo con groupBy invoicer: las cifras del grupo por servicio propio del proveedor (Amazon Bedrock, con los modelos del marketplace que factura; Amazon SageMaker; Vertex AI; ...), tal como las muestra la pestaña Cloud de la página Gasto.

  • unattributedArray<object>

    Solo con groupBy costCenter: el gasto que ninguna regla de atribución ha asignado, una entrada por moneda con la forma de un grupo, visible y nunca oculto. Escribe una regla para él con SetAiAttribution.

  • notReadableArray<object>

    Las cuentas conectadas sin líneas de IA, y por qué: needs_current_cost para una cuenta de AWS cuya conexión no permite el coste actual (AWS da sus líneas de IA solo a través de Cost Explorer), not_synced_yet para una cuyas líneas de IA aún no se han leído. No aparece cuando no hay ninguna.

Errores

  • 400 Bad Request - period no es un mes en formato YYYY-MM, o groupBy no es invoicer, vendor, model ni costCenter.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
GET /v1/workspaces/{regionId}/ai-spend
Solicitud
GET /v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.buyer/ai-spend?period=2026-10&groupBy=vendor
Respuesta · 200 OK
{
   "period": "2026-10",
   "asOf": "2026-10-29T06:10:00.000Z",
   "totals": [
      { "currency": "USD", "monthToDate": 57280.14, "forecast": 61400, "lastMonth": 48930.55, "changePct": 25.5 }
   ],
   "groups": [
      {
         "key": "anthropic",
         "label": "Anthropic",
         "invoicer": "aws",
         "invoicerId": "conn_01k7q2n4m8b3xd5fwj9hz6rsvt",
         "currency": "USD",
         "monthToDate": 44612.3,
         "forecast": 47830,
         "lastMonth": 38104.2,
         "changePct": 25.5,
         "quantities": [
            { "meter": "input_tokens", "unit": "1M_tokens", "quantity": 7120.4 },
            { "meter": "output_tokens", "unit": "1M_tokens", "quantity": 918.3 },
            { "meter": "cached_input_tokens", "unit": "1M_tokens", "quantity": 15480 },
            { "meter": "cache_write_tokens", "unit": "1M_tokens", "quantity": 1288.7 }
         ],
         "purchaseOrders": [ { "poId": "PO-8842", "lineNo": 1, "remaining": 4200 } ]
      },
      {
         "key": "amazon",
         "label": "Amazon",
         "invoicer": "aws",
         "invoicerId": "conn_01k7q2n4m8b3xd5fwj9hz6rsvt",
         "currency": "USD",
         "monthToDate": 12667.84,
         "forecast": 13570,
         "lastMonth": 10826.35,
         "changePct": 25.3,
         "quantities": [
            { "meter": "input_tokens", "unit": "1M_tokens", "quantity": 10874.8 },
            { "meter": "output_tokens", "unit": "1M_tokens", "quantity": 1240 }
         ],
         "purchaseOrders": [ { "poId": "PO-8842", "lineNo": 1, "remaining": 4200 } ]
      }
   ]
}

Listar líneas de uso de IA

Lista las líneas de uso de IA que hay detrás de las cifras, página a página.

GET/v1/workspaces/{regionId}/ai-spend/lines

Parámetros

  • periodstring

    El mes, YYYY-MM. Por defecto, el mes en curso.

  • invoicerIdstring

    Solo líneas facturadas a través de esta conexión de nube.

  • vendorstring

    Solo este proveedor de modelos, p. ej. anthropic.

  • modelstring

    Solo este id de modelo tal como se factura, p. ej. claude-sonnet-4-5.

  • costCenterstring

    Solo líneas atribuidas a este centro de coste (su código). Las líneas se atribuyen según las reglas de atribución.

  • limitnumber

    Tamaño de página, de 1 a 500. Por defecto, 100.

  • cursorstring

    El nextCursor de la página anterior. Omítelo para la primera página.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Las líneas normalizadas de las que se suma el gasto en IA: una por facturador, día, proveedor del modelo, modelo, medidor y región, tal como las informó la facturación del proveedor. Cada conector lee sus propios nombres (tipos de uso de AWS Cost Explorer, SKU de la exportación de facturación de Google Cloud, medidores de Azure Cost Management, SKU de uso de OCI) y los mapea a un proveedor de modelo, un modelo y un medidor; un tipo de uso que Pleaxy aún no conoce se conserva con su nombre original y vendor unknown, nunca se descarta. Del día más reciente al más antiguo. Pasa el nextCursor de una página como cursor para obtener la siguiente, y sigue hasta que nextCursor no aparezca. Las líneas se conservan con detalle diario durante 90 días y después por mes.

Campos de la respuesta

  • invoicerstring

    La nube en cuya factura está la línea, con invoicerId como su conexión. Es el proveedor, sea cual sea el proveedor del modelo.

  • vendorstring

    La empresa cuyo modelo se usó, leída del tipo de uso, el SKU o el nombre del medidor. unknown cuando Pleaxy aún no ha mapeado ese tipo de uso; rawUsageType dice entonces cómo lo llamó el proveedor.

  • modelstring

    El id del modelo tal como lo factura el proveedor, p. ej. claude-sonnet-4-5 o gemini-2.5-pro.

  • shapestring

    tokens para una línea medida en tokens (proveedor del modelo × modelo × medidor × región); capacity para capacidad aprovisionada, horas de GPU o un clúster dedicado (proveedor del modelo × sku × medidor).

  • meterstring

    input_tokens, output_tokens, cached_input_tokens, cache_write_tokens, batch_input_tokens, batch_output_tokens, images, audio_seconds, embeddings_tokens o requests para tokens; gpu_hours, ptu_hours, model_units_hours o cluster_hours para capacidad; other, con unit units, para un tipo de uso que Pleaxy aún no ha mapeado.

  • daystring

    YYYY-MM-DD. Pasados 90 días, las líneas se conservan por mes y day es entonces el primer día del mes.

  • amountnumber

    Lo que el proveedor cobra por la línea, antes de impuestos, en currency: tal como lo informa el proveedor, nunca convertido.

  • unitPricenumber

    amount dividido entre quantity, en la unidad de la tarifa, cuando quantity es mayor que 0: lo que se cobró efectivamente por la línea, para compararlo con ListAiRateCards.

  • attributionobject

    Cómo atribuye la línea el propio proveedor, con los nombres que usa: una etiqueta de asignación de costes o un perfil de inferencia de aplicación (AWS), una etiqueta o un proyecto (Google Cloud), un grupo de recursos o una etiqueta (Azure), un compartimento (OCI). Ausente cuando la línea no lleva ninguno.

  • sourcestring

    De qué lectura procede la línea: AWS Cost Explorer (cost_explorer), la exportación de facturación de BigQuery de Google Cloud (billing_export), Azure Cost Management (cost_management) o la API de uso de OCI (usage_api).

  • rawServicestring

    El nombre del servicio según el propio proveedor y, como rawUsageType, su tipo de uso, SKU o nombre de medidor, conservados para auditorías y en cada línea sin mapear.

  • nextCursorstring

    Opaco. Ausente cuando no hay líneas más antiguas.

Errores

  • 400 Bad Request - period no es un mes en formato YYYY-MM, limit está fuera de rango, o cursor no es uno devuelto por esta ruta.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
GET /v1/workspaces/{regionId}/ai-spend/lines
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-spend/lines" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
{
   "lines": [
      {
         "invoicerId": "string",
         "invoicer": "aws" | "gcp" | "azure" | "oci" | "openai" | "anthropic" | "mistral" | "snowflake",
         "vendor": "anthropic" | "openai" | "google" | "meta" | "mistral" | "amazon" | "microsoft" | "cohere" | "xai" | "deepseek" | "unknown",
         "model": "string",
         "shape": "tokens" | "capacity",
         "meter": "string",
         "region": "string",
         "day": "string",
         "quantity": number,
         "unit": "1M_tokens" | "tokens" | "requests" | "images" | "seconds" | "gpu_hours" | "ptu_hours" | "model_unit_hours" | "units",
         "amount": number,
         "currency": "string",
         "unitPrice": number,
         "attribution": { "tag": "string", "label": "string", "project": "string", "resourceGroup": "string", "compartment": "string", "inferenceProfile": "string" },
         "source": "cost_explorer" | "billing_export" | "cost_management" | "usage_api",
         "rawService": "string",
         "rawUsageType": "string"
      }
   ],
   "nextCursor": "string"
}

Listar tarifas de IA

Lista los precios de lista públicos de los modelos de IA, vigentes en un día.

GET/v1/workspaces/{regionId}/ai-rate-cards

Parámetros

  • invoicer"aws" | "gcp" | "azure" | "oci"

    Solo los precios de este facturador.

  • vendorstring

    Solo los modelos de este proveedor de modelos, p. ej. anthropic.

  • modelstring

    Solo este id de modelo tal como se factura.

  • onstring

    Un día, YYYY-MM-DD: solo la entrada vigente ese día, por facturador, proveedor de modelo, modelo, medidor y región. Si se omite, se devuelven todas las entradas.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Los precios de lista públicos que Pleaxy mantiene para cada facturador, proveedor de modelo, modelo, medidor y región que mapea, con fechas de vigencia, tomados de las páginas de precios de los propios proveedores. Un cambio de precio es una entrada nueva con su propio effectiveFrom; nada se edita en el sitio, así que una línea se juzga siempre frente al precio que regía en su día. Con on, solo se devuelve la entrada vigente ese día por facturador, proveedor de modelo, modelo, medidor y región; sin él, todas las entradas, pasadas y actuales. La tarifa negociada de un contrato o su descuento sobre el precio de lista prevalece sobre la tarifa cuando Pleaxy comprueba tus líneas; las tarifas en sí no se pueden editar.

Campos de la respuesta

  • unitPricenumber

    El precio de lista por unidad, en currency: por 1,000,000 de tokens para 1M_tokens, por hora para las unidades de capacidad.

  • regionstring

    Solo cuando el facturador fija precios por región; ausente para un precio que aplica en todas partes.

  • effectiveFromstring

    El día en que el precio entró en vigor, YYYY-MM-DD, y como effectiveTo, una vez sustituido, el último día en que se aplicó. Sin effectiveTo: sigue vigente.

  • sourceUrlstring

    La página de precios del proveedor de la que se tomó la entrada.

Errores

  • 400 Bad Request - on no es un día en formato YYYY-MM-DD, o invoicer no es aws, gcp, azure ni oci.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
GET /v1/workspaces/{regionId}/ai-rate-cards
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-rate-cards" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
[
   {
      "invoicer": "aws" | "gcp" | "azure" | "oci" | "openai" | "anthropic" | "mistral" | "snowflake",
      "vendor": "string",
      "model": "string",
      "meter": "string",
      "region": "string",
      "unit": "1M_tokens" | "tokens" | "requests" | "images" | "seconds" | "gpu_hours" | "ptu_hours" | "model_unit_hours",
      "unitPrice": number,
      "currency": "string",
      "effectiveFrom": "string",
      "effectiveTo": "string",
      "sourceUrl": "string"
   }
]

Comprobar gasto en IA

Dice si la previsión del periodo cabe en las líneas de orden de compra abiertas y en el presupuesto.

POST/v1/workspaces/{regionId}/ai-spend/check

Cuerpo

  • invoicerIdstring

    La conexión de nube a comprobar: su previsión frente a todas las líneas de orden de compra abiertas emitidas a su nombre.

  • costCenterstring

    El código o nombre de un centro de coste: su gasto en IA atribuido y su previsión frente a su presupuesto del periodo, cuando los presupuestos están activados. Las líneas se atribuyen según las reglas de atribución.

  • poIdstring

    Una orden de compra: solo sus líneas abiertas, para el facturador al que se emitió.

  • periodstring

    El mes, YYYY-MM. Por defecto, el mes en curso.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Responde a «¿cabrá Bedrock en PO-8842 este mes?» con las mismas cifras que GetAiSpend: el mes en curso y la previsión de un facturador, un centro de coste o una orden de compra, frente a las líneas de orden de compra abiertas emitidas a ese facturador y, con un centro de coste y los presupuestos activados, su presupuesto. No se guarda nada y nada se bloquea: el resultado es lo que muestra la pestaña IA de la página Gasto y lo que responden el Asistente y la herramienta MCP check_ai_spend. Indica al menos uno de invoicerId, costCenter y poId; poId implica el facturador al que se emitió.

Campos de la respuesta

  • outcomestring

    fits: la previsión cabe en lo que queda en las líneas abiertas (y en el presupuesto). over: no cabe; el overBy de cada línea dice por cuánto, y budget.remaining pasa a ser negativo. no_po: no hay ninguna línea de orden de compra abierta emitida al facturador para el periodo. no_budget: se indicó un centro de coste pero no tiene presupuesto para el periodo, o los presupuestos están desactivados.

  • currencystring

    La moneda de facturación del facturador, en la que están monthToDate, forecast y las cifras de las líneas. Nada se convierte: un presupuesto en otra moneda da no_budget.

  • purchaseOrdersArray<object>

    Las líneas abiertas comprobadas, cada una con remaining tras las facturas ya cargadas contra ella y, cuando la previsión lo supera, overBy.

  • budgetobject

    Solo con costCenter y los presupuestos activados: el presupuesto del centro de coste para el periodo, committed (órdenes de compra abiertas), actual (facturas), accruing (gasto en IA atribuido del mes en curso, aún no facturado: una tercera cifra, nunca fusionada con las otras dos) y remaining.

Errores

  • 400 Bad Request - No se indicó ninguno de invoicerId, costCenter y poId, o period no es un mes en formato YYYY-MM.
  • 404 Not Found - No hay ninguna conexión de nube, centro de coste ni orden de compra con ese id en el espacio de trabajo.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
POST /v1/workspaces/{regionId}/ai-spend/check
Solicitud
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-spend/check" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "invoicerId": "string",
   "costCenter": "string",
   "poId": "string",
   "period": "string"
}
Respuesta · 200 OK
{
   "outcome": "fits" | "over" | "no_po" | "no_budget",
   "period": "string",
   "currency": "string",
   "monthToDate": number,
   "forecast": number,
   "purchaseOrders": [ { "poId": "string", "lineNo": number, "remaining": number, "overBy": number } ],
   "budget": { "costCenter": "string", "budget": number, "committed": number, "actual": number, "accruing": number, "remaining": number }
}

Sugerir líneas de orden de compra de IA

Líneas de orden de compra rellenadas a partir del uso de IA de un facturador.

GET/v1/workspaces/{regionId}/ai-spend/po-lines

Parámetros

  • invoicerIdstringObligatorio

    El facturador del que procede el uso de las líneas: groups[].invoicerId de GetAiSpend.

  • periodstring

    El mes, YYYY-MM. Por defecto, el último mes cerrado.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Las líneas que "Agregar líneas de IA" rellena en una orden de compra: para un facturador y un mes (por defecto, el último mes cerrado), una línea por cada modelo y medidor que facturó, con el volumen del mes redondeado hacia arriba como cantidad y un precio unitario tomado de la condición vigente de tu contrato para ese modelo (su tarifa o su descuento sobre el precio de lista) o, si no, del precio de lista de hoy o, si no, de lo que se facturó en el mes; priceSource indica cuál. No se ofrecen las líneas que Pleaxy no pudo asignar a un medidor ni los créditos sin precio en dinero. No se guarda nada: envía las líneas a CreatePurchaseOrder, con el contractId que indique cada línea. Necesita acceso 'view' a las órdenes de compra.

Campos de la respuesta

  • providerstring

    Para un facturador de nube: el proveedor al que emitir la orden. Un proveedor de IA directo da en su lugar supplierConnectionId, su entrada de proveedor.

  • lines[].aiobject

    El alcance de IA de la línea, para enviarlo como lineItems[].ai.

  • lines[].unitstring

    La unidad del medidor: 1M_tokens para un medidor de tokens, gpu_hours y similares para capacidad.

  • lines[].priceSourcestring

    contract (contractId y contractTermId indican la condición), list (la tarifa en la fecha de hoy) o billed (lo que costó el mes por unidad, cuando Pleaxy no tiene precio para el modelo).

  • lines[].periodQuantitynumber

    Lo que se consumió en el mes, con periodAmount lo que se facturó, para que el formulario de la orden lo muestre junto a la línea.

Errores

  • 400 Bad Request - Falta invoicerId, o period no es un mes en formato YYYY-MM.
  • 404 Not Found - No hay ningún facturador conectado con ese id en el espacio de trabajo.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
GET /v1/workspaces/{regionId}/ai-spend/po-lines
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-spend/po-lines" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
{
   "invoicerId": "string",
   "invoicer": "string",
   "period": "string",
   "provider": "string",
   "supplierConnectionId": "string",
   "lines": [
      {
         "ai": { "invoicer": "string", "vendor": "string", "model": "string", "meter": "string", "region": "string" },
         "unit": "string",
         "qty": number,
         "unitPrice": number,
         "currency": "string",
         "priceSource": "contract" | "list" | "billed",
         "contractId": "string",
         "contractTermId": "string",
         "periodQuantity": number,
         "periodAmount": number
      }
   ]
}

Emitir el siguiente periodo de IA

Crea un borrador de la misma orden para el mes siguiente.

POST/v1/workspaces/{regionId}/ai-spend/next-period/{poId}

Parámetros

  • poIdstringObligatorio

    La orden que se vuelve a emitir: una con líneas de IA, o la orden de un proveedor de nube.

Devuelve

201 Created con el objeto que se muestra en la respuesta.

Más detalles

"Emitir el siguiente periodo": un borrador de la misma orden (proveedor, centro de coste, contrato y líneas) para el mes posterior al de sus líneas. La cantidad de cada línea de IA es la previsión a partir del uso de este mes hasta ahora, lineal sobre los días transcurridos (su propia cantidad cuando aún no se ha usado nada); las demás líneas conservan su cantidad. El borrador pasa por la aprobación habitual al enviarse. No lleva cuerpo. Necesita acceso 'create' a las órdenes de compra.

Errores

  • 400 Bad Request - La orden no tiene líneas de IA y no es una orden de nube.
  • 404 Not Found - No existe esa orden en el espacio de trabajo.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
POST /v1/workspaces/{regionId}/ai-spend/next-period/{poId}
Solicitud
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-spend/next-period/{poId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 201 Created
PurchaseOrder (the draft), as GetPurchaseOrder returns it

Obtener recomendaciones de IA

Gasto en IA que ninguna orden cubre, y formas más baratas de comprarlo.

GET/v1/workspaces/{regionId}/ai-spend/recommendations

Parámetros

  • periodstring

    El mes cuya cobertura se comprueba, YYYY-MM. Por defecto, este mes.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Lo que recomienda la pestaña IA de la página Gasto. uncovered enumera cada facturador cuyo pronóstico del mes no cubre ninguna orden de compra abierta: no_po cuando no hay ninguna orden emitida a su nombre, over_po cuando el pronóstico supera lo que les queda a sus órdenes, con gap el importe que necesita una orden nueva. savings enumera formas más baratas de comprar el uso del mes pasado, con los precios de lista de hoy: batch (lo máximo que ahorraría pasar los tokens interactivos a la tarifa por lotes), cache (lo que ahorra cada 10% adicional de entrada leída de la caché) y reserve (horas de GPU usadas con un mínimo estable la mayoría de los días, y las GPU que ese mínimo mantiene ocupadas; sin importe, porque las reservas se fijan por contrato). No se listan importes inferiores a 10, y cada importe queda en la moneda de facturación del facturador. Requiere acceso 'view' a proveedores o a facturas.

Campos de la respuesta

  • basisPeriodstring

    El mes del que se leen los ahorros: el último cerrado.

  • uncovered[].coverednumber

    Lo que les queda para el mes a las líneas de órdenes abiertas emitidas a este facturador.

  • uncovered[].gapnumber

    forecast menos covered: lo que necesita una orden nueva. DraftAiOrders crea su borrador.

  • uncovered[].poIdsstring[]

    Para over_po, las órdenes abiertas que cubren una parte.

  • accountsobject[]

    Lo mismo que uncovered para cuentas de nube completas: todo su gasto, según la estimación actual del proveedor, frente a las órdenes abiertas que cubren la cuenta. Solo este mes. El gasto en IA de una cuenta forma parte de él, así que nunca sumes las dos listas.

  • savings[].savingnumber

    batch: lo máximo que ahorra al mes si todo se ejecutara por lotes (solo conviene al trabajo que puede esperar). cache: lo que ahorra al mes cada 10% adicional de entrada servida desde la caché. No aparece para reserve.

  • savings[].detail.cachedSharenumber

    cache: la parte de la entrada que ya se lee de la caché, de 0 a 1.

  • savings[].detail.reservableUnitsnumber

    reserve: las GPU que el mínimo estable de steadyHoursPerDay mantiene ocupadas día y noche, en daysUsed días del mes.

Errores

  • 400 Bad Request - period no es un mes en formato YYYY-MM.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
GET /v1/workspaces/{regionId}/ai-spend/recommendations
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-spend/recommendations" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
{
   "period": "string",
   "basisPeriod": "string",
   "uncovered": [
      {
         "invoicerId": "string",
         "invoicer": "string",
         "label": "string",
         "currency": "string",
         "monthToDate": number,
         "forecast": number,
         "covered": number,
         "gap": number,
         "reason": "no_po" | "over_po",
         "poIds": [ "string" ]
      }
   ],
   "accounts": [ "same as uncovered, for whole cloud accounts" ],
   "savings": [
      {
         "kind": "batch" | "cache" | "reserve",
         "invoicerId": "string",
         "invoicer": "string",
         "label": "string",
         "vendor": "string",
         "model": "string",
         "currency": "string",
         "spend": number,
         "saving": number,
         "detail": { "interactiveRate": number, "batchRate": number, "inputRate": number, "cachedRate": number, "cachedShare": number, "daysUsed": number, "steadyHoursPerDay": number, "reservableUnits": number }
      }
   ]
}

Crear borradores de órdenes de IA

Crea el borrador de una orden para el gasto en IA sin cubrir de cada facturador.

POST/v1/workspaces/{regionId}/ai-spend/draft-orders

Cuerpo

  • invoicerIdsstring[]Obligatorio

    Los facturadores para los que crear una orden, de 1 a 20: uncovered[].invoicerId de GetAiRecommendations.

  • periodstring

    El mes que cubren las órdenes, YYYY-MM. Por defecto, este mes.

  • scopestring

    ai (por defecto): líneas por modelo y medidor para el uso de IA. account: una línea por importe para todo lo que factura una cuenta de nube, hasta su gap en accounts, hasta fin de mes.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

"Crear borrador de orden" en una recomendación: para cada facturador indicado, el borrador de una orden de compra del mes con una línea por modelo y medidor del uso del mes pasado, con los precios que pone SuggestAiPoLines, y como cantidad de cada una el pronóstico a partir del uso de este mes hasta hoy. Cuando las órdenes abiertas ya cubren parte del pronóstico, las cantidades se ajustan a la diferencia. El borrador de una nube se emite al proveedor para esa cuenta; el de un proveedor de IA directo, a su registro de proveedor. skipped indica por qué un facturador no obtuvo borrador. Los borradores pasan por la aprobación habitual al enviarse. Requiere acceso 'create' a órdenes de compra.

Campos de la respuesta

  • drafts[].poIdstring

    El borrador de la orden: GetPurchaseOrder lo lee, y al enviarlo pasa a aprobación.

  • skipped[].reasonstring

    no_usage: todavía no hay uso de IA en el que basar una orden. no_supplier: un proveedor de IA directo sin registro de proveedor al que emitirla. no_forecast (scope account): todavía no hay una estimación de gasto actual para la cuenta. already_drafted: ya hay un borrador, o una orden pendiente de aprobación, para este gasto este mes; poId la identifica y no se crea un segundo borrador.

Errores

  • 400 Bad Request - invoicerIds está vacío o tiene más de 20, period no es un mes con formato YYYY-MM, o scope es account para un facturador que no es una cuenta de nube.
  • 404 Not Found - Ningún facturador conectado con alguno de esos ids en el espacio de trabajo.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
POST /v1/workspaces/{regionId}/ai-spend/draft-orders
Solicitud
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-spend/draft-orders" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "invoicerIds": [ "string" ],
   "period": "string",
   "scope": "ai" | "account"
}
Respuesta · 200 OK
{
   "period": "string",
   "drafts": [ { "invoicerId": "string", "poId": "string", "currency": "string", "total": number } ],
   "skipped": [ { "invoicerId": "string", "reason": "no_usage" | "no_supplier" | "no_forecast" | "already_drafted", "poId": "string", "message": "string", "messageId": "string", "params": { } } ]
}

Listar compromisos de IA

Gasto y capacidad de IA comprometidos, y créditos prepagados, con lo consumido.

GET/v1/workspaces/{regionId}/ai-spend/commitments

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Lo que muestra la pestaña Compromisos de la página Gasto: cada condición de tus contratos vigentes con un gasto comprometido o una capacidad reservada, con lo que el uso de IA sincronizado ha consumido de ella dentro de su vigencia, lo que queda y, para el gasto, el ritmo hasta el final de la condición; y cada línea de orden de crédito prepagado con lo que han consumido sus facturas. Necesita acceso 'view' a los proveedores o a las facturas.

Campos de la respuesta

  • committednumber

    spend: el importe comprometido, en currency. capacity: las unidades reservadas por las horas transcurridas de la condición. prepaid_credit: lo que compró la línea de la orden.

  • usednumber

    spend: los importes de las líneas de IA sincronizadas que cubre la condición, en su moneda. capacity: las horas usadas. prepaid_credit: lo que las facturas han consumido de la línea.

  • projectednumber

    Solo spend: lo que la condición habrá consumido a su fin al ritmo actual.

Errores

  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
GET /v1/workspaces/{regionId}/ai-spend/commitments
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-spend/commitments" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
[
   {
      "kind": "spend" | "capacity" | "prepaid_credit",
      "contractId": "string",
      "contractTitle": "string",
      "termId": "string",
      "poId": "string",
      "lineNo": number,
      "supplier": "string",
      "description": "string",
      "ai": { "invoicer": "string", "vendor": "string", "model": "string", "meter": "string" },
      "currency": "string",
      "termStart": "string",
      "termEnd": "string",
      "committed": number,
      "used": number,
      "remaining": number,
      "usedPct": number,
      "projected": number,
      "unit": "string"
   }
]

Obtener regla de renovación de IA

La regla que crea los borradores de las órdenes de IA del mes siguiente.

GET/v1/workspaces/{regionId}/ai-spend/renewal-rule

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Si las órdenes de IA del mes siguiente se crean como borrador a partir de la previsión, desde qué día del mes, y qué borradores creó su última ejecución. Desactivada hasta que alguien la active. Necesita acceso 'view' a las órdenes de compra.

Campos de la respuesta

  • ownerSubstring

    Quién la activó: los borradores se emiten en su nombre mientras siga siendo miembro del espacio de trabajo.

  • draftedForstring

    El último mes para el que se emitieron borradores, YYYY-MM: cada mes se crea una sola vez.

Errores

  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
GET /v1/workspaces/{regionId}/ai-spend/renewal-rule
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-spend/renewal-rule" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
{
   "enabled": boolean,
   "dayOfMonth": number,
   "ownerSub": "string",
   "updatedAt": "string",
   "draftedFor": "string",
   "lastRun": { "at": "string", "period": "string", "drafts": [ { "poId": "string", "draftId": "string" } ] }
}

Definir regla de renovación de IA

Activa o desactiva la regla de renovación de órdenes de IA.

PUT/v1/workspaces/{regionId}/ai-spend/renewal-rule

Cuerpo

  • enabledbooleanObligatorio

    Si las órdenes de IA del mes siguiente se crean como borrador.

  • dayOfMonthnumber

    De 1 a 28: el día a partir del cual se emiten los borradores. 25 si se omite.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

A partir de dayOfMonth, una vez al mes, Pleaxy crea el borrador de la orden del mes siguiente para cada orden abierta con líneas de IA válidas este mes, como hace RaiseNextAiPeriod, en nombre de quien activó la regla. La regla se ejecuta la próxima vez que se lee el gasto en IA del espacio de trabajo (el panel y la página Gasto lo leen). Los borradores nunca se emiten sin la aprobación habitual.

Sesión iniciada con acceso 'create' a las órdenes de compra; una clave de API recibe 403.

Errores

  • 400 Bad Request - dayOfMonth no es un número entero de 1 a 28.
  • 403 Forbidden - El llamador es una clave de API o no tiene acceso 'create' a las órdenes de compra.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
PUT /v1/workspaces/{regionId}/ai-spend/renewal-rule
Solicitud
curl -X PUT "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-spend/renewal-rule" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "enabled": true,
   "dayOfMonth": 25
}
Respuesta · 200 OK
The rule, as GetAiRenewalRule returns it

Obtener atribución de IA

Las reglas que atribuyen el gasto en IA a centros de coste.

GET/v1/workspaces/{regionId}/ai-spend/attribution

Parámetros

  • periodstring

    El mes, YYYY-MM. Por defecto, el mes en curso.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Tus reglas de atribución en orden - gana la primera que coincide con una línea -, con lo que asignó cada una en el periodo, lo que no asignó ninguna regla y los valores de dimensión detrás del gasto sin asignar (de mayor a menor), para escribir a partir de ellos la siguiente regla. Una regla asigna una dimensión del proveedor a un centro de coste: tag (etiqueta de asignación de costes de AWS) o label (Google Cloud), con su clave; project (OpenAI, Google Cloud), workspace (Anthropic), resource_group (Azure), compartment (OCI), cluster (nubes de GPU), api_key o inference_profile. Una línea con la que no coincide ninguna regla queda sin atribuir: visible, nunca oculta. Necesita acceso 'view' a los proveedores o a las facturas.

Campos de la respuesta

  • versionnumber

    Devuélvelo con SetAiAttribution, para que un guardado no pueda sobrescribir el de otra persona.

  • rules[].invoicerIdstring

    Solo las líneas de ese facturador; todos los facturadores si no aparece.

  • rules[].matchedArray<object>

    Lo que asignó la regla en el periodo, una entrada por moneda.

Errores

  • 400 Bad Request - period no es un mes en formato YYYY-MM.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
GET /v1/workspaces/{regionId}/ai-spend/attribution
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-spend/attribution" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
{
   "period": "string",
   "version": number,
   "updatedAt": "string",
   "rules": [
      { "id": "string", "invoicerId": "string", "dimension": "string", "key": "string", "value": "string", "costCenter": "string", "matched": [ { "currency": "string", "amount": number } ] }
   ],
   "unattributed": [ { "currency": "string", "amount": number } ],
   "unmatchedValues": [ { "invoicerId": "string", "key": "string", "value": "string", "currency": "string", "amount": number } ]
}

Definir atribución de IA

Sustituye las reglas de atribución.

PUT/v1/workspaces/{regionId}/ai-spend/attribution

Cuerpo

  • rulesArray<{ id?, invoicerId?, dimension, key?, value, costCenter }>Obligatorio

    Todas las reglas, de la que coincide primero a la última. Como máximo 200. Conserva el id de una regla para mantenerla; una regla nueva recibe uno.

  • versionnumberObligatorio

    La versión que devolvió GetAiAttribution; 0 para el primer guardado.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Sustituye todas las reglas, en orden, a partir de la versión que leíste. Una regla tag o label necesita su clave; el centro de coste debe ser uno de los del espacio de trabajo. Una regla sobre una etiqueta de AWS o de Google Cloud hace que la siguiente sincronización lea también por ella las líneas de IA de esa cuenta (una clave de etiqueta de AWS por cuenta). Devuelve las reglas como GetAiAttribution. Necesita acceso 'edit' a las órdenes de compra.

Errores

  • 400 Bad Request - Una regla tag o label no tiene clave, o un centro de coste no es uno de los del espacio de trabajo.
  • 409 Conflict - Alguien guardó las reglas después de que las leyeras; vuelve a leerlas.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
PUT /v1/workspaces/{regionId}/ai-spend/attribution
Solicitud
curl -X PUT "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-spend/attribution" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "rules": [ { "dimension": "tag", "key": "team", "value": "search", "costCenter": "CC-410" } ],
   "version": 3
}
Respuesta · 200 OK
The rules, as GetAiAttribution returns them

Listar centros de coste de IA

Presupuestos de los centros de coste con el gasto en IA que van acumulando.

GET/v1/workspaces/{regionId}/ai-spend/cost-centers

Parámetros

  • periodstring

    El mes, YYYY-MM. Por defecto, el mes en curso.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

El presupuesto de cada centro de coste, committed (órdenes aprobadas) y actual (facturas aprobadas) del control de presupuestos, con el uso de IA atribuido de este mes como accruing - una tercera cifra, aún no facturada - y su previsión, en la moneda del presupuesto; el porcentaje del presupuesto con la previsión; y la alerta enviada. Cuando la previsión más lo comprometido y lo facturado alcanza el 80% o el 100% de un presupuesto, Pleaxy envía una notificación ai_forecast_over_budget una vez por umbral y por mes, a través de los canales del espacio de trabajo. Nada se bloquea. Necesita acceso 'view' a las órdenes de compra.

Campos de la respuesta

  • budgetModestring

    El modo del control de presupuestos. off: no se llevan presupuestos, las filas solo traen las cifras de IA y no se envía ninguna alerta.

  • rows[].pctWithForecastnumber

    (committed + actual + forecast) / budget, en porcentaje. Ausente sin presupuesto.

Errores

  • 400 Bad Request - period no es un mes en formato YYYY-MM.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
GET /v1/workspaces/{regionId}/ai-spend/cost-centers
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-spend/cost-centers" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
{
   "period": "string",
   "budgetMode": "string",
   "thresholds": [ number ],
   "rows": [
      { "costCenter": "string", "costCenterName": "string", "currency": "string", "budget": number, "committed": number, "actual": number, "accruing": number, "forecast": number, "pctWithForecast": number, "alert": { "threshold": number, "sentAt": "string" } }
   ],
   "unattributed": [ { "currency": "string", "monthToDate": number, "forecast": number } ]
}

Listar límites de gasto en IA

Los topes de gasto fijados en los proveedores, y sus credenciales.

GET/v1/workspaces/{regionId}/ai-spend/limits

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Opcional, hay que activarlo: los topes de gasto que Pleaxy fijó en los proveedores a partir de tus líneas de orden aprobadas, y qué facturadores tienen una credencial de límites (nunca la clave). Un tope es tu propio límite en el proveedor - un presupuesto de AWS, un límite de proyecto de OpenAI, un límite de espacio de trabajo de Anthropic, un presupuesto o un límite de gasto de Google Cloud, un presupuesto de Azure -, fijado con una credencial que creas aparte de la conexión de solo lectura y que puedes quitar cuando quieras. Necesita acceso 'view' a las órdenes de compra.

Campos de la respuesta

  • limits[].enforcementstring

    deny: el proveedor detiene el gasto en el tope (un límite de OpenAI o de Anthropic, un límite de gasto de Google Cloud, una acción de presupuesto de AWS que adjunta tu política de denegación; AWS actualiza los presupuestos unas pocas veces al día, así que llega con horas de retraso). alert: solo notifica (Azure, o un presupuesto de Google Cloud o de AWS sin ella).

  • limits[].readBackobject

    Lo que dio volver a leer el tope en el proveedor, y cuándo.

  • limits[].historyArray<object>

    Cada escritura que hizo Pleaxy para la línea en el proveedor, las 20 últimas.

Errores

  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
GET /v1/workspaces/{regionId}/ai-spend/limits
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-spend/limits" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
{
   "credentials": [ { "invoicerId": "string", "invoicer": "aws" | "openai" | "anthropic" | "gcp" | "azure", "keyHint": "string", "notifyEmail": "string", "createdAt": "string" } ],
   "limits": [
      {
         "poId": "string", "lineNo": number, "invoicerId": "string", "invoicer": "string", "target": "string",
         "amount": number, "currency": "string", "period": "string", "providerRef": "string",
         "enforcement": "deny" | "alert", "state": "set" | "failed" | "removed",
         "readBack": { "amount": number, "at": "string" },
         "history": [ { "at": "string", "by": "string", "action": "set" | "raise" | "remove" | "failed", "amount": number, "readBack": number, "error": "string" } ]
      }
   ]
}

Definir límite de gasto en IA

Fija el importe de una línea de orden aprobada como tope del proveedor.

PUT/v1/workspaces/{regionId}/ai-spend/limits/{poId}/{lineNo}

Parámetros

  • poIdstringObligatorio

    La orden aprobada.

  • lineNonumberObligatorio

    La línea de la orden cuyo importe es el tope.

Cuerpo

  • invoicerIdstringObligatorio

    La cuenta o el proveedor de IA que cubre la orden, con una credencial de límites.

  • targetstring

    OpenAI: el proyecto (proj_...). Anthropic: el espacio de trabajo (wrkspc_...). Google Cloud: el proyecto, para un límite de gasto.

  • denyboolean

    Detener el gasto en el tope cuando el proveedor puede hacerlo. true si se omite; false solo alerta.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Escribe el importe de la línea como tope de gasto de su facturador para el mes (el primer mes de la línea si empieza más tarde), lo vuelve a leer y registra la escritura. Solo para una orden aprobada y abierta emitida a ese facturador, con una credencial de límites para él. Se rechaza por debajo del gasto del mes en curso, con las cifras. Aumentar la línea (una nueva versión) sube el tope; cerrar la orden lo quita. Pleaxy nunca cambia ni elimina en el proveedor nada que no haya creado. Necesita acceso 'edit' a las órdenes de compra.

Con sesión iniciada a través de un agente, es una solicitud de agente que la persona confirma en Pleaxy; una clave de API con 'edit' en las órdenes de compra actúa de inmediato.

Errores

  • 400 Bad Request - La orden no está aprobada y abierta, o no está emitida a ese facturador; no hay credencial de límites para él; el tope quedaría por debajo del gasto del mes en curso; o el proveedor lo rechazó (el motivo dice por qué: la credencial, un proyecto o espacio de trabajo que falta, una moneda que no admite).
  • 404 Not Found - No existe esa orden, línea o facturador, o los límites no están activados en esta región.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
PUT /v1/workspaces/{regionId}/ai-spend/limits/{poId}/{lineNo}
Solicitud
curl -X PUT "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-spend/limits/{poId}/{lineNo}" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "invoicerId": "aip_01k8q2m4xv7c9n3p5t6r8w0yzb",
   "target": "proj_abc"
}
Respuesta · 200 OK
The limit, as an entry of ListAiSpendLimits' limits

Quitar límite de gasto en IA

Quita el tope que Pleaxy fijó para una línea de orden.

DELETE/v1/workspaces/{regionId}/ai-spend/limits/{poId}/{lineNo}

Parámetros

  • poIdstringObligatorio

    La orden.

  • lineNonumberObligatorio

    La línea de la orden.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Elimina el tope que Pleaxy fijó para la línea en el proveedor (solo uno con el nombre que le puso Pleaxy) y lo registra. Necesita acceso 'edit' a las órdenes de compra.

Errores

  • 404 Not Found - No hay ningún tope para esa línea.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
DELETE /v1/workspaces/{regionId}/ai-spend/limits/{poId}/{lineNo}
Solicitud
curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-spend/limits/{poId}/{lineNo}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
The limit, as an entry of ListAiSpendLimits' limits, with state removed

Definir credencial de límites de IA

Agrega la credencial aparte con la que se fijan los topes de un facturador.

PUT/v1/workspaces/{regionId}/ai-spend/limit-credentials/{invoicerId}

Parámetros

  • invoicerIdstringObligatorio

    El id de la conexión de nube o del proveedor de IA.

Cuerpo

  • roleArnstring

    AWS: el ARN del rol PleaxyAiLimits.

  • executionRoleArnstring

    AWS, para detener el gasto: el ARN del rol de ejecución de la plantilla.

  • denyPolicyArnstring

    AWS, para detener el gasto: el ARN de la política de denegación de la plantilla.

  • roleNamesArray<string>

    AWS, para detener el gasto: los nombres de los roles a los que se adjunta la política de denegación.

  • serviceAccountEmailstring

    Google Cloud: la cuenta de servicio de límites.

  • clientIdstring

    Azure: el ID de cliente de la aplicación de límites.

  • keystring

    OpenAI o Anthropic: una clave de administrador aparte para los límites.

  • notifyEmailstring

    A quién escribe el proveedor al llegar a un tope: necesario para Azure y para un tope de AWS que detiene el gasto.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

La credencial de escritura para los topes de un facturador, separada de su conexión de solo lectura, que nunca se amplía: un rol de límites de AWS (de la plantilla de CloudFormation aws-ai-limits de Pleaxy: solo AWS Budgets y, opcionalmente, una política de denegación sobre las llamadas a Amazon Bedrock que el presupuesto adjunta al 100%), una cuenta de servicio de límites de Google Cloud en el grupo de identidades de la conexión, una aplicación de límites de Azure con la credencial federada de la conexión, o una clave de administrador aparte de OpenAI o de Anthropic (guardada cifrada, nunca devuelta). Se comprueba con una lectura antes de guardarla. Quítala para dejar de usar la función con ese facturador.

Sesión iniciada con acceso 'edit' a los proveedores; una clave de API recibe 403.

Errores

  • 400 Bad Request - Falta un campo que el proveedor necesita; es la propia credencial de la conexión de solo lectura; o el proveedor la rechazó, y no se guardó nada.
  • 403 Forbidden - El llamador es una clave de API o no tiene 'edit' en los proveedores.
  • 404 Not Found - No existe ese facturador, o los límites no están activados en esta región.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
PUT /v1/workspaces/{regionId}/ai-spend/limit-credentials/{invoicerId}
Solicitud
curl -X PUT "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-spend/limit-credentials/{invoicerId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "roleArn": "arn:aws:iam::123456789012:role/PleaxyAiLimits"
}
Respuesta · 200 OK
The credential, as an entry of ListAiSpendLimits' credentials

Quitar credencial de límites de IA

Quita la credencial de límites de un facturador.

DELETE/v1/workspaces/{regionId}/ai-spend/limit-credentials/{invoicerId}

Parámetros

  • invoicerIdstringObligatorio

    El id de la conexión de nube o del proveedor de IA.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Pleaxy deja de fijar topes en ese facturador; la conexión de solo lectura sigue como estaba. Elimina también el rol, la cuenta de servicio, la aplicación o la clave en el proveedor.

Sesión iniciada con acceso 'edit' a los proveedores; una clave de API recibe 403.

Errores

  • 403 Forbidden - El llamador es una clave de API o no tiene 'edit' en los proveedores.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
DELETE /v1/workspaces/{regionId}/ai-spend/limit-credentials/{invoicerId}
Solicitud
curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-spend/limit-credentials/{invoicerId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
{
   "invoicerId": "string"
}

Listar recuentos de puestos de IA

Usuarios activos de un mes en los productos de IA por puesto.

GET/v1/workspaces/{regionId}/ai-spend/seats

Parámetros

  • periodstring

    El mes, YYYY-MM. Por defecto, el mes en curso.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

La IA por puesto (ChatGPT Enterprise, Claude Enterprise, Microsoft 365 Copilot, GitHub Copilot, Cursor) se factura por puesto. Estos son los usuarios activos registrados para cada producto en un mes, y de dónde salió cada recuento. Una línea de factura con medidor seats que factura más puestos que el recuento del mes es un hallazgo ai_seats_above_active; una condición de contrato que compromete puestos aparece en la pestaña Compromisos frente al último recuento. Necesita acceso 'view' a los proveedores o a las facturas.

Errores

  • 400 Bad Request - period no es un mes en formato YYYY-MM.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
GET /v1/workspaces/{regionId}/ai-spend/seats
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-spend/seats" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
[
   { "invoicer": "string", "product": "string", "period": "string", "activeUsers": number, "source": "okta" | "entra" | "google_workspace" | "jumpcloud" | "provider_console" | "manual", "recordedAt": "string", "recordedBy": "string" }
]

Definir recuento de puestos de IA

Registra los usuarios activos de un mes en un producto por puesto.

PUT/v1/workspaces/{regionId}/ai-spend/seats

Cuerpo

  • invoicerstringObligatorio

    Quién factura los puestos: openai, anthropic, microsoft, github, cursor, ...

  • productstringObligatorio

    El producto por puesto tal como lo nombra la línea de la orden (su ai.model), p. ej. chatgpt-enterprise.

  • periodstringObligatorio

    El mes, YYYY-MM.

  • activeUsersnumberObligatorio

    Usuarios con un puesto que iniciaron sesión ese mes.

  • sourcestringObligatorio

    okta, entra, google_workspace, jumpcloud, provider_console o manual.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Registra cuántos usuarios de un producto por puesto estuvieron activos en un mes, según lo informa tu proveedor de identidad (Okta, Microsoft Entra, Google Workspace, JumpCloud) o la consola de administración del proveedor, y sustituye el recuento de ese mes. Pleaxy no lee tu proveedor de identidad por sí mismo: envía el recuento desde un script, un agente o a mano. Necesita acceso 'edit' a las facturas.

Errores

  • 400 Bad Request - Falta un campo o está fuera de rango.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
PUT /v1/workspaces/{regionId}/ai-spend/seats
Solicitud
curl -X PUT "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-spend/seats" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "invoicer": "openai",
   "product": "chatgpt-enterprise",
   "period": "2026-10",
   "activeUsers": 182,
   "source": "okta"
}
Respuesta · 200 OK
The count, as an entry of ListAiSeatCounts
Habla con nosotros