Consumo / Uso

Consulta el consumo de tu proyecto: tokens y costo estimado de extracción (LLM) más volumen de OCR (documentos y páginas).

Requiere el scope usage:read.

Endpoint

GET https://ocr.789.com.mx/v1/usage
X-API-Key: ocr_live_xxxxxxxxxxxxxxxx
Accept: application/json

Parámetros (query)

Si to es anterior a from recibes 422 validation_error. Si solo envías un to anterior al mes en curso, el periodo queda invertido y todo sale en cero: envía siempre from junto con to.

Ejemplo

curl "https://ocr.789.com.mx/v1/usage?from=2026-06-01&to=2026-06-30" \
  -H "X-API-Key: ocr_live_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

Respuesta

{
  "data": {
    "period": { "from": "2026-06-01T00:00:00+00:00", "to": "2026-06-30T23:59:59+00:00" },
    "currency": "USD",
    "extraction": {
      "extractions": 42,
      "runs": 45,
      "input_tokens": 120000,
      "output_tokens": 38000,
      "total_tokens": 158000,
      "estimated_cost": 0.59
    },
    "ocr": {
      "documents": 50,
      "pages": 320,
      "bytes": 18874368
    },
    "project_id": "prj_xxxxxxxx",
    "estimated": true
  },
  "meta": { "request_id": "..." }
}

Notas

• El consumo es por proyecto: refleja todo lo procesado por las API Keys del proyecto en todos sus ambientes (test, staging, live), no solo la key con la que consultas.
• extraction.extractions cuenta las extracciones con al menos un intento en el periodo; extraction.runs cuenta los intentos (cada reintento contra el modelo es un run).
• Tokens y estimated_cost suman todos los intentos, incluidos reintentos y extracciones que terminaron en failed o validation_failed.
• estimated_cost es estimado: usa el precio acordado para tu proyecto cuando existe y, si no, el precio del modelo dado de alta en la plataforma. El precio se fija al procesar cada intento, así que un cambio de precio no altera consumos ya registrados. Los intentos sin precio o sin tokens reportados por el proveedor cuentan como 0. Úsalo como referencia, no como facturación exacta.
• bytes es el tamaño total de los documentos originales subidos en el periodo.