É possível concluir, apenas com a resposta de incidents do UptimeScout, que um serviço está fora do ar? Não: esse endpoint lista serviços com sinais elevados recentes de falhas, e a especificação ressalta expressamente que eles não são incidentes confirmados pelo provedor. Na prática, o resultado é uma lista breve de sinais a verificar, não uma conclusão pronta sobre a causa da falha.

Essa distinção é útil para o engenheiro de plantão e o analista: um alerta automático pode informar “verifique o serviço X na região Y”, deixando a confirmação do fato e a explicação da causa a cargo do status oficial do provedor ou do diagnóstico interno. A especificação do UptimeScout documenta rotas separadas para sinais, status atual e histórico de observações.
O que a lista de sinais retorna
/v1/incidents é um endpoint GET que lista serviços com sinais elevados de falhas. Seus parâmetros incluem filtros por serviço, região, categoria, termo de pesquisa e período de tempo. A resposta exige licença; a API descreve autenticação por token Bearer. O campo de região aceita um código de duas letras, e hours define um período de 1 a 2160 horas.
É fácil interpretar a palavra “incident” no caminho como “interrupção confirmada”, mas a documentação define um significado mais restrito: um sinal recente de observação. Por isso, formule o alerta de acordo com os dados da resposta — por exemplo, “foi recebido um sinal de falha de disponibilidade” — e não atribua ao provedor do serviço o reconhecimento de um incidente.
Verificação mínima antes de alertar
Primeiro, guarde a resposta original junto com o horário de recebimento e os parâmetros da consulta. Em seguida, confira qual serviço e região foram retornados e avalie a atualidade pelos campos do serviço observed_at e stale. Se a observação estiver marcada como desatualizada, separe-a do sinal atual em vez de apresentá-la como o estado “neste momento”.
curl -sS 'https://api.uptimescout.com/v1/incidents?region=US&hours=24' \
-H "Authorization: Bearer $UPTIMESCOUT_LICENSE_KEY"
Este exemplo consulta os Estados Unidos em um período de 24 horas; a chave é lida de uma variável de ambiente e não é exibida na linha de comando. Após receber a resposta, verifique os erros HTTP e a estrutura do JSON e, em seguida, processe cada serviço retornado separadamente. Os valores de status previstos no esquema incluem operational, degraded, outage e unknown; se um campo ou valor estiver ausente, não substitua por uma interpretação própria.
Para um sinal que exija ação, consulte o status atual do serviço correspondente por meio de /v1/status e o histórico por meio de /v1/history. No histórico, é útil guardar junto das séries resolution_seconds, samples, counts e effective_start: assim, o analista vê a resolução temporal dos dados e o intervalo efetivamente disponível. A especificação alerta que os intervalos ausentes são desconhecidos; um período sem dados não pode ser automaticamente considerado nem disponibilidade nem falha.
Como transformar a resposta em um relatório verificável
Para cada registro, crie campos para o identificador e o nome do serviço, a região consultada, o status, o horário da observação, o indicador de desatualização, o horário de recebimento da resposta e um link para a fonte do status oficial, caso a equipe o tenha verificado. Esse último campo é preenchido pela sua integração ou por um operador: a especificação do UptimeScout não garante que o sinal inclua uma causa confirmada ou uma declaração do provedor.

Divida o fluxo de trabalho em três estados. “Sinal recebido” significa que o registro apareceu no resultado de /v1/incidents. “Status em verificação” significa que você consultou o estado atual e o histórico. Reserve “Confirmado” para uma conclusão sustentada por um comunicado oficial externo ou por uma verificação interna. Essa simples distinção impede que o painel apresente um sinal agregado como um fato estabelecido.
Se a equipe criar um relatório para várias regiões, faça consultas separadas com os códigos regionais necessários e guarde o parâmetro junto com o resultado. O campo lang diz respeito ao idioma das descrições dos serviços; ele não altera a região das observações. Essa distinção é importante, por exemplo, ao comparar um catálogo localizado com o estado regional.
Onde termina a conclusão
O resultado verificável desse procedimento é um registro de sinais com horários, região e atualidade claramente indicados, complementado por uma verificação separada do status e do histórico. Ele ajuda a identificar o que exige atenção e o que foi possível confirmar com as fontes selecionadas. A resposta de /v1/incidents informa sobre um sinal elevado de observação; para declarar uma interrupção confirmada, são necessários dados que a corroborem.