Monitoramento e Data Warehouse

O Proton entrega o que acontece nas automações para as ferramentas da empresa de duas formas:

• Puxar, pela API de consulta: execuções, logs, métricas, ocorrências, runners e eventos, com carga incremental. É o caminho para o Data Warehouse, o Power BI e os painéis corporativos.
• Receber, pelos webhooks: o Proton avisa na hora, com uma mensagem assinada, quando uma execução termina, um lote não roda, uma ocorrência abre ou um runner cai. É o caminho para a ferramenta de monitoramento e de chamados.

As duas fazem parte do plano Enterprise.

1. Acesso só de leitura

A integração não deve depender de uma pessoa nem poder alterar nada. Por isso, use um usuário robô com um perfil só de leitura e um token que só consulta:

1. Perfil: em Acesso & Equipes > Perfil, crie um perfil (por exemplo, "Leitura para integrações") só com as permissões de visualizar do que a integração vai ler: Execuções, Ocorrências, Runners, Automações, Grupos de automação e Ambientes.
2. Usuário robô: em Acesso & Equipes > Usuário, use Criar conta robô e dê a ele esse perfil.
3. Token: nos Tokens de API do robô, gere um token com a opção Só a API de consulta (leitura). Esse token só faz as leituras da API de consulta e recebe 403 em qualquer outra rota. Guarde o token no cofre de segredos da empresa: ele aparece uma vez só.

No portal, Configurações > API de consulta reúne esses três passos, com a situação de cada um: os tokens de consulta da organização (dono, último uso e vencimento), o endereço base e exemplos prontos em curl, Python e Power BI. O botão Gerar token de consulta pergunta para quem é o token (de preferência um robô) e já cria o token só de consulta.

Equipes

A API segue a mesma regra das telas: a automação restrita a uma equipe só aparece para quem está nela. Para a integração ver tudo, deixe o robô nas equipes certas ou com um perfil de administrador da organização.

2. A primeira chamada

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

A resposta traz as execuções mais recentes, com a automação, o dataset, o grupo, o ambiente, o runner, o status, o motivo do fim, a duração e o 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": "Cadastro de fornecedor" },
      "environment": { "id": 2, "name": "Produção", "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 listagem incremental lê na ordem em que as coisas aconteceram e devolve, em nextCursor, onde a leitura parou, inclusive na última página. A carga guarda esse cursor e, na próxima rodada, volta com ele: recebe só o que chegou depois, sem repetir nem pular.

Tabela no Data Warehouse	Rota	Primeira carga	Chave
Execuções	/v1/runs	finishedSince	id
Linhas do log	/v1/logs	from	id
Ocorrências	/v1/exceptions	updatedSince	id (a ocorrência volta quando muda)
Eventos	/v1/events	since	id
Automações, grupos e ambientes	/v1/automations, /v1/groups, /v1/environments	Carga completa	id

Grave pelo id (inserir ou atualizar): assim, repetir uma página nunca duplica a linha.

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")

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


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


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


def carregar(rota, chave, estado, primeira_carga, gravar):
    """Lê a rota desde o último cursor guardado (ou desde a primeira carga) e grava cada página."""
    parametros = {"cursor": estado[chave]} if chave in estado else dict(primeira_carga)
    while True:
        resposta = sessao.get(f"{BASE}{rota}", params={**parametros, "limit": 500}, timeout=60)
        if resposta.status_code == 429:
            time.sleep(int(resposta.headers.get("Retry-After", "60")))
            continue
        resposta.raise_for_status()
        pagina = resposta.json()

        gravar(pagina["data"])  # inserir ou atualizar pelo id

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


estado = ler_estado()
carregar("/runs", "runs", estado, {"finishedSince": "2026-10-01T00:00:00Z"}, gravar_execucoes)
carregar("/logs", "logs", estado, {"from": "2026-10-01T00:00:00Z"}, gravar_linhas_do_log)
carregar("/exceptions", "exceptions", estado, {"updatedSince": "2026-10-01T00:00:00Z"}, gravar_ocorrencias)
carregar("/events", "events", estado, {"since": "2026-10-01T00:00:00Z"}, gravar_eventos)

Rode a carga no intervalo que a empresa precisar (de 5 em 5 minutos, de hora em hora). As funções gravar_... são as do seu Data Warehouse.

4. Indicadores prontos

Para um painel que não precisa dos dados linha a linha, /v1/metrics entrega os indicadores do período já calculados: disponibilidade dos runners, taxa de sucesso e de falha, tempo médio de processamento (com o p95), MTTR, reprocessamentos, tempo fora do ar e a tendência por dia ou semana, por automação, grupo, ambiente ou 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"

O que cada indicador conta está na referência.

Boas práticas

• Limite: são 600 chamadas por token a cada 5 minutos. Ao receber 429, espere o tempo do cabeçalho Retry-After e continue do mesmo cursor.
• Datas: tudo vem em UTC (ISO 8601). Converta para o fuso da empresa na hora de exibir.
• Campos novos: a v1 só cresce. Trate campo desconhecido como opcional e não quebre a carga por causa dele.
• Um token por integração: se um vazar, revogue só ele, em Tokens de API do robô.
• Correlation ID: o mesmo id aparece nas execuções, no log e nos sistemas que a automação chamou. Use para cruzar o Proton com os logs do resto da empresa.