# UptimeScout: como verificar se houve uma falha no serviço na região do usuário

https://jsonscraper.com/pt/blog/verificar-falha-servico-regiao-usuario

Author: Michael Johnson

Published: 2026-11-20T11:40:43+00:00

Updated: 2026-11-20T11:40:43+00:00

Um caso prático: reunir o histórico de observações por região e distinguir um sinal recente de um intervalo desconhecido

Quando usuários de um país relatam problemas, mas a equipe vê o serviço funcionando normalmente, é mais útil verificar as observações especificamente da região deles. A API do UptimeScout permite consultar o histórico de um serviço selecionado por código regional e obter intervalos com o número de medições. O resultado é uma tabela verificável para analisar o relato: horário do intervalo, resolução, distribuição dos sinais e quantidade de amostras.



![Artigo: UptimeScout: como verificar se houve uma falha no serviço na região do usuário
Resumo: A verificação regional de disponibilidade pode ajudar a determinar se um incidente relatado por um usuário coincidiu com as observações do UptimeScout. Veja um procedimento reproduzível: escolha o serviço e a região, consulte o histórico, verifique a atualidade e a resolução dos dados e salve o resultado junto com a resposta original.
Função da imagem: capa — ideia central
Seção: 
Tema visual: fotografia editorial de um mapa regional de interrupções dobrado](https://jsonscraper.com/assets/uploads/journal/2026/11/1cd4023e50fafa3c2411a7c5fc1a0f4b.png.hero.webp)

A região e o intervalo de tempo delimitam a verificação de disponibilidade.© jsonscraper · criado com IA

 

O cenário prático é diagnosticar uma possível falha regional. Dados de entrada: o identificador do serviço no catálogo do UptimeScout, um código regional como US ou GB e um intervalo do histórico. O resultado ajuda a comparar o horário do relato do usuário com as observações do serviço. A própria API descreve os dados como sinais de disponibilidade observada; a verificação do serviço é útil para localizar a questão, não para substituir as verificações da aplicação.

 

## Primeiro, confirme o serviço e a região

 

Comece pelo catálogo: encontre o serviço desejado pelo nome ou pela busca e registre seu ID exato. A especificação [OpenAPI do UptimeScout](https://uptimescout.com/openapi.json) descreve a busca por meio de GET /v1/services e dos parâmetros q, service, region, limit e offset. Para um relatório de diagnóstico, é melhor armazenar o ID, e não apenas o nome exibido: assim, uma nova consulta apontará para o mesmo item do catálogo.

 

A região é definida por um código próprio de duas letras. É importante salvá-la junto com o resultado: uma resposta para US e outra sem filtro regional respondem a perguntas diferentes. Se a descrição precisar ser exibida em português, o parâmetro lang=pt controla a localização da descrição, enquanto o parâmetro region seleciona as observações. A documentação distingue explicitamente essas duas funções.

 

## Consulte o histórico, não apenas um status

 

Para analisar um incidente, use /v1/history com o parâmetro obrigatório service e a region selecionada. O parâmetro hours define o intervalo do histórico; a especificação permite valores de 1 a 2160 horas. A consulta também prevê lang. De acordo com a OpenAPI, a autorização é feita com uma licença no esquema Bearer. Na execução prática, mantenha a chave em uma variável de ambiente e não a registre no log das consultas.

 

```
import os
import requests

response = requests.get(
    "https://api.uptimescout.com/v1/history",
    headers={"Authorization": f"Bearer {os.environ['UPTIMESCOUT_LICENSE_KEY']}"},
    params={"service": "github", "region": "GB", "hours": 24, "lang": "ru"},
    timeout=30,
)
response.raise_for_status()
data = response.json()
print(data)
```

 

Este é um exemplo mínimo de consulta, não um resultado publicado de uma investigação real. O identificador github e a região GB são parâmetros ilustrativos: antes de aplicar o exemplo, escolha o serviço e a região relevantes para seu caso. É útil salvar a resposta completa em JSON e adicionar o horário de recebimento e a descrição da consulta em campos separados do seu sistema de auditoria. Assim, é possível repetir a análise e identificar exatamente qual captura de dados foi usada.

 

## Resolução e lacunas fazem parte do resultado

 

No array history, são importantes os campos observed_at, resolution_seconds, aggregated, samples e counts. A resolução informa a duração do intervalo; samples indica quantas observações foram incluídas na agregação, e counts contém a distribuição dos sinais. Analise esses campos em conjunto: uma linha com poucas amostras tem um peso diferente para a análise de uma agregação com muitas observações.



![Artigo: UptimeScout: como verificar se houve uma falha no serviço na região do usuário
Resumo: A verificação regional de disponibilidade pode ajudar a determinar se um incidente relatado por um usuário coincidiu com as observações do UptimeScout. Veja um procedimento reproduzível: escolha o serviço e a região, consulte o histórico, verifique a atualidade e a resolução dos dados e salve o resultado junto com a resposta original.
Função da imagem: ilustração de apoio 2 — um aspecto específico diferente
Seção: Resolução e lacunas fazem parte do resultado](https://jsonscraper.com/assets/uploads/journal/2026/11/a171063a93107bb525c54a0ee477e61a.png.hero.webp)

Como ler o histórico: região, intervalos de tempo, resolução e lacunas.© jsonscraper · ilustração gerada por IA

 

O UptimeScout descreve o histórico como intervalos de tempo com granularidade variável conforme o período selecionado: intervalos de um e cinco minutos para períodos curtos, horários para um dia e diários para períodos longos. Agregações antigas armazenadas podem ter uma resolução mais grosseira. Portanto, não conclua que “a falha começou exatamente neste minuto” se a linha representa uma agregação horária ou diária. Use os valores efetivos de resolution_seconds e os campos effective_start e history_resolution da resposta para delimitar o que os dados permitem concluir.

 

Trate um intervalo ausente como desconhecido. A especificação pede expressamente que lacunas sejam consideradas intervalos desconhecidos: um espaço vazio no histórico, por si só, não representa nem funcionamento normal nem falha. Essa regra simples evita que relatórios preencham lacunas indevidamente com um status “verde” ou com zeros.

 

## Compare o histórico com o sinal atual

 

Se precisar verificar o estado no momento do relato, consulte /v1/status para o mesmo service e region. No objeto do serviço, observe conjuntamente status, observed_at e stale; a documentação apresenta esses campos como forma de compreender o estado e a atualidade do sinal. O status de nível superior se refere ao resultado da consulta à API, enquanto service.status descreve o sinal de disponibilidade do serviço específico. Essa distinção é especialmente útil em relatórios automatizados: uma resposta HTTP bem-sucedida e o estado de um serviço externo são coisas diferentes.

 

Para várias dependências, você pode consultar /v1/statuses e depois usar o histórico apenas para os serviços e regiões em que ocorreu uma anomalia. A especificação também oferece /v1/summary e /v1/incidents. Ao diagnosticar esta última rota, considere sua função exata: o endpoint retorna sinais recentes de interrupção em nível elevado, não incidentes confirmados pelo próprio fornecedor. Portanto, o resultado serve como motivo para conferência, não como conclusão definitiva sobre a causa.

 

## Como apresentar uma conclusão sem especular

 

Na linha do relatório, salve o ID do service, a region, o período da consulta, observed_at, resolution_seconds, samples, counts e a indicação de lacunas. Adicione o link para o relato ou incidente interno separadamente dos campos da API. Em seguida, compare o intervalo de tempo com os logs da aplicação, os rastreamentos regionais e o relato do usuário. Se o intervalo da agregação for mais amplo que o incidente, formule o resultado de acordo: as observações da região selecionada, durante o período especificado, contêm determinados sinais, com uma resolução e uma quantidade de amostras específicas.

 

Essa análise oferece à pessoa de plantão uma direção útil: verificar a parte regional do serviço externo ou continuar o diagnóstico da própria aplicação e da rede do usuário. A possibilidade de reproduzi-la depende de salvar os parâmetros da consulta e o JSON original; a qualidade das conclusões temporais depende de considerar explicitamente a resolução, as amostras e os períodos desconhecidos. Esse é o resultado prático de um caso de disponibilidade: não apenas um rótulo de status atual, mas um registro delimitado por região e tempo que outra pessoa pode verificar.
