pnclENGINEObter acesso à API

SAÚDE DO FEED

Observe o próprio batimento do feed.

Quando um quadro fica parado, a primeira pergunta é de quem é a culpa: do seu poller ou da fonte. A API de odds da Pinnacle responde diretamente em dois endpoints de status: um /health autenticado com detalhe por feed, e um /ping público que retorna um simples ok. Faça polling deles em um loop lento e uma degradação aparece no seu painel antes de aparecer no seu produto.

Obter acesso à API

O que o /health reporta

Um GET com sua chave de API retorna o estado operacional dos dois feeds. Os campos de topo descrevem apenas o feed ao vivo: status é healthy ou degraded com um degraded_reason opcional, live_write_age_ms são os milissegundos desde a última escrita ao vivo, source diz se os dados ao vivo chegam por ws, rest ou none, e version é o mesmo cursor que os endpoints de quadro retornam como last.

{
  "status": "healthy",
  "degraded_reason": null,
  "live_write_age_ms": 546,
  "source": "ws",
  "events_in_store": 145,
  "version": 50352678,
  "prematch": {
    "enabled": true,
    "status": "healthy",
    "write_age_ms": 71,
    "version": 50352723
  }
}

O objeto aninhado prematch é um segundo serviço, não um detalhe. Ele carrega seu próprio status, que também pode ser unreachable, e seu próprio write_age_ms e version. Um lado pode estar degradado enquanto o outro está bem, e o status de topo nunca muda por um problema de pré-jogo, então um monitor que lê só o campo de topo está cego para metade do feed.

Ligue isso ao seu monitor

Faça polling do /health uma vez por minuto por ambiente; cada chamada é uma requisição no seu plano, então é um batimento barato, não um segundo poller. Alerte em duas condições: status saindo de healthy em qualquer feed, e live_write_age_ms ou prematch.write_age_ms cruzando seu orçamento de frescura. As duas idades normalmente ficam bem abaixo de um segundo, então uma leitura nas dezenas de milhares já é uma história.

Duas sutilezas mantêm os alertas honestos. Trate unreachable de pré-jogo como desconhecido, não como fora: significa que o próprio health check não alcançou o serviço de pré-jogo enquanto os dados podem estar bem. E compare version com o cursor que seu poller guardou por último, porque cursores iguais provam que seu pipeline lê o mesmo feed que a página de status descreve. Para balanceadores de carga e sondas de uptime que não podem enviar cabeçalho de autenticação, o /ping é público e retorna ok em texto puro.

Quando o feed degrada

Uma leitura degradada é motivo para segurar, não para martelar. Continue servindo o último snapshot bom com sua idade visível, alargue seu intervalo de polling para não somar carga enquanto o feed se recupera, e deixe os números de frescura da próxima chamada ao /health decidirem quando apertar de novo. Chame uma pessoa só quando a degradação durar mais que a tolerância que seu produto anunciou.

Este endpoint vigia a fonte; seu próprio pipeline ainda precisa das cinco métricas do lado do consumidor no guia de monitoramento de pipeline, e um período degradado pode aparecer como respostas de erro comuns, que o runbook de erros cobre. A página de status no guia de SSE da pnclPULSE é a referência para como um stream saudável se parece ao longo do tempo.

Perguntas que isso levanta

O /health é autenticado?

Sim, ele aceita a mesma chave de API de qualquer outro endpoint, no cabeçalho ou no parâmetro key. O /ping é o público, feito para sondas que não podem enviar credenciais.

Com que frequência devo consultar o /health?

Uma vez por minuto por ambiente basta. Cada chamada conta como uma requisição no seu plano, então cinco painéis consultando a cada cinco segundos somam cota real sem sinal extra.

Pré-jogo unreachable significa pré-jogo fora do ar?

Não. Significa que o health check não conseguiu alcançar o serviço de pré-jogo; os dados em si podem estar bem. Trate a leitura como desconhecida e confirme com a frescura do seu próprio poll de pré-jogo.

Posso confiar só no status de topo?

Não. Ele descreve apenas o feed ao vivo. Uma queda de pré-jogo nunca o move, então observe prematch.status e prematch.write_age_ms como séries separadas.

Os campos de status e o comportamento dos endpoints seguem a documentação publicada do fornecedor, verificada em 29 de outubro de 2026. Publicado em .

Obter acesso à API