Monitoreo y Data Warehouse

Proton entrega lo que pasa en las automatizaciones a las herramientas de la empresa de dos formas:

• Consultar, por la API de consulta: ejecuciones, logs, métricas, ocurrencias, runners y eventos, con carga incremental. Es el camino para el Data Warehouse, Power BI y los paneles corporativos.
• Recibir, por los webhooks: Proton avisa al momento, con un mensaje firmado, cuando una ejecución termina, un lote no se ejecuta, se abre una ocurrencia o un runner se cae. Es el camino para la herramienta de monitoreo y de tickets.

Las dos forman parte del plan Enterprise.

1. Acceso de solo lectura

La integración no debe depender de una persona ni poder cambiar nada. Por eso, usa un usuario robot con un perfil de solo lectura y un token que solo consulta:

1. Perfil: en Acceso & Equipos > Perfil, crea un perfil (por ejemplo, "Lectura para integraciones") solo con los permisos de ver de lo que la integración va a leer: Ejecuciones, Ocurrencias, Runners, Automatizaciones, Grupos de automatización y Ambientes.
2. Usuario robot: en Acceso & Equipos > Usuario, usa Crear cuenta robot y dale ese perfil.
3. Token: en los Tokens de API del robot, genera un token con la opción Solo la API de consulta (lectura). Ese token solo hace las lecturas de la API de consulta y recibe 403 en cualquier otra ruta. Guarda el token en el almacén de secretos de la empresa: aparece una sola vez.

En el portal, Configuraciones > API de consulta reúne estos tres pasos, con la situación de cada uno: los tokens de consulta de la organización (dueño, último uso y vencimiento), la dirección base y ejemplos listos en curl, Python y Power BI. El botón Generar token de consulta pregunta para quién es el token (de preferencia un robot) y ya crea el token de solo consulta.

Equipos

La API sigue la misma regla de las pantallas: la automatización restringida a un equipo solo aparece para quien está en él. Para que la integración vea todo, deja el robot en los equipos correctos o con un perfil de administrador de la organización.

2. La primera llamada

curl -s https://app.protoncloud.com.br/api/v1/runs?limit=5 \
  -H "Authorization: Bearer $PROTON_TOKEN_CONSULTA"

La respuesta trae las ejecuciones más recientes, con la automatización, el dataset, el grupo, el ambiente, el runner, el estado, el motivo del fin, la duración y el Correlation ID:

{
  "data": [
    {
      "id": 48211,
      "correlationId": "7f6c2d2e-5f0b-4a4a-9b9b-3c1f2a9e0d11",
      "state": "finished",
      "status": "failed",
      "endReason": "technical_error",
      "startedAt": "2026-10-19T14:58:00.000Z",
      "finishedAt": "2026-10-19T15:00:00.000Z",
      "durationMs": 120000,
      "automation": { "id": 5, "name": "Registro de proveedor" },
      "environment": { "id": 2, "name": "Producción", "production": true },
      "link": "https://app.protoncloud.com.br/automations/center/dataset/40/cycle/7/dataset-run/48211/details"
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJvIjoiZGlzcGF0Y2hlZCIsImsiOls0ODIxMV19"
}

3. Carga incremental

Cada listado incremental lee en el orden en que las cosas ocurrieron y devuelve, en nextCursor, dónde se detuvo la lectura, incluso en la última página. La carga guarda ese cursor y, en la próxima ronda, vuelve con él: recibe solo lo que llegó después, sin repetir ni saltar.

Tabla en el Data Warehouse	Ruta	Primera carga	Clave
Ejecuciones	/v1/runs	finishedSince	id
Líneas del log	/v1/logs	from	id
Ocurrencias	/v1/exceptions	updatedSince	id (la ocurrencia vuelve cuando cambia)
Eventos	/v1/events	since	id
Automatizaciones, grupos y ambientes	/v1/automations, /v1/groups, /v1/environments	Carga completa	id

Graba por id (insertar o actualizar): así, repetir una página nunca duplica la fila.

Python

import json
import os
import time
from pathlib import Path

import requests

BASE = "https://app.protoncloud.com.br/api/v1"
ESTADO = Path("estado_proton.json")

sesion = requests.Session()
sesion.headers["Authorization"] = f"Bearer {os.environ['PROTON_TOKEN_CONSULTA']}"


def leer_estado():
    return json.loads(ESTADO.read_text()) if ESTADO.exists() else {}


def guardar_estado(estado):
    ESTADO.write_text(json.dumps(estado))


def cargar(ruta, clave, estado, primera_carga, grabar):
    """Lee la ruta desde el último cursor guardado (o desde la primera carga) y graba cada página."""
    parametros = {"cursor": estado[clave]} if clave in estado else dict(primera_carga)
    while True:
        respuesta = sesion.get(f"{BASE}{ruta}", params={**parametros, "limit": 500}, timeout=60)
        if respuesta.status_code == 429:
            time.sleep(int(respuesta.headers.get("Retry-After", "60")))
            continue
        respuesta.raise_for_status()
        pagina = respuesta.json()

        grabar(pagina["data"])  # insertar o actualizar por el id

        if pagina["nextCursor"]:
            estado[clave] = pagina["nextCursor"]
            guardar_estado(estado)
        if not pagina["hasMore"]:
            return
        parametros = {"cursor": pagina["nextCursor"]}


estado = leer_estado()
cargar("/runs", "runs", estado, {"finishedSince": "2026-10-01T00:00:00Z"}, grabar_ejecuciones)
cargar("/logs", "logs", estado, {"from": "2026-10-01T00:00:00Z"}, grabar_lineas_del_log)
cargar("/exceptions", "exceptions", estado, {"updatedSince": "2026-10-01T00:00:00Z"}, grabar_ocurrencias)
cargar("/events", "events", estado, {"since": "2026-10-01T00:00:00Z"}, grabar_eventos)

Ejecuta la carga en el intervalo que la empresa necesite (cada 5 minutos, cada hora). Las funciones grabar_... son las de tu Data Warehouse.

4. Indicadores listos

Para un panel que no necesita los datos fila por fila, /v1/metrics entrega los indicadores del período ya calculados: disponibilidad de los runners, tasa de éxito y de falla, tiempo promedio de procesamiento (con el p95), MTTR, reprocesamientos, tiempo fuera de línea y la tendencia por día o semana, por automatización, grupo, ambiente o runner.

curl -s "https://app.protoncloud.com.br/api/v1/metrics?from=2026-10-01T00:00:00Z&groupBy=day" \
  -H "Authorization: Bearer $PROTON_TOKEN_CONSULTA"

Lo que cuenta cada indicador está en la referencia.

Buenas prácticas

• Límite: son 600 llamadas por token cada 5 minutos. Al recibir 429, espera el tiempo del encabezado Retry-After y sigue desde el mismo cursor.
• Fechas: todo viene en UTC (ISO 8601). Convierte a la zona horaria de la empresa al mostrar.
• Campos nuevos: la v1 solo crece. Trata un campo desconocido como opcional y no rompas la carga por él.
• Un token por integración: si uno se filtra, revoca solo ese, en los Tokens de API del robot.
• Correlation ID: el mismo id aparece en las ejecuciones, en el log y en los sistemas que llamó la automatización. Úsalo para cruzar Proton con los logs del resto de la empresa.