API — Histórico de Checks

O endpoint de checks retorna o histórico de verificações realizadas em um monitor. Use para calcular uptime personalizado, exportar dados para análise, alimentar dashboards externos ou plotar gráficos de tempo de resposta.

GET /monitors/:id/checks

Retorna os checks de um monitor em ordem decrescente (mais recente primeiro).

curl "https://api.thealert.io/api/v1/monitors/mon_abc123/checks" \
  -H "Authorization: Bearer ta_sua_chave"

Resposta:

{
  "data": [
    {
      "id": "chk_001",
      "status": "UP",
      "responseTime": 142,
      "statusCode": 200,
      "errorMessage": null,
      "checkedAt": "2026-03-23T15:00:00.000Z"
    },
    {
      "id": "chk_002",
      "status": "DOWN",
      "responseTime": null,
      "statusCode": null,
      "errorMessage": "connect ETIMEDOUT",
      "checkedAt": "2026-03-23T14:59:00.000Z"
    },
    {
      "id": "chk_003",
      "status": "DEGRADED",
      "responseTime": 8450,
      "statusCode": 503,
      "errorMessage": "Service Unavailable",
      "checkedAt": "2026-03-23T14:58:00.000Z"
    }
  ],
  "meta": {
    "total": 3,
    "monitorId": "mon_abc123"
  }
}

Campos da resposta

Campo	Tipo	Descrição
`id`	string	ID único do check
`status`	string	`UP`, `DOWN` ou `DEGRADED`
`responseTime`	number \| null	Latência em milissegundos; `null` quando DOWN por timeout/erro de conexão
`statusCode`	number \| null	Status code HTTP retornado; `null` para checks não-HTTP ou sem resposta
`errorMessage`	string \| null	Descrição do erro quando DOWN/DEGRADED; `null` quando UP
`checkedAt`	string	Data/hora do check em ISO 8601 (UTC)

Parâmetros de query

limit

Número de checks a retornar. Padrão: 50. Máximo: 500.

# Retornar os últimos 100 checks
curl "https://api.thealert.io/api/v1/monitors/mon_abc123/checks?limit=100" \
  -H "Authorization: Bearer ta_sua_chave"

since

Retornar apenas checks a partir de uma data/hora específica. Formato: ISO 8601.

# Checks das últimas 24 horas
SINCE=$(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ)
 
curl "https://api.thealert.io/api/v1/monitors/mon_abc123/checks?since=${SINCE}&limit=500" \
  -H "Authorization: Bearer ta_sua_chave"

Combine since com limit=500 para buscar um volume maior de checks de um período específico.

Exemplos de uso

Calcular uptime das últimas 24 horas

const response = await fetch(
  `https://api.thealert.io/api/v1/monitors/${monitorId}/checks?limit=500&since=${since24h}`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
)
const { data: checks } = await response.json()
 
const total = checks.length
const upChecks = checks.filter(c => c.status === 'UP').length
const uptime = ((upChecks / total) * 100).toFixed(2)
 
console.log(`Uptime (24h): ${uptime}%`)

Exportar histórico para CSV

import requests
import csv
from datetime import datetime, timedelta
 
API_KEY = 'ta_sua_chave'
MONITOR_ID = 'mon_abc123'
 
since = (datetime.utcnow() - timedelta(days=7)).isoformat() + 'Z'
 
response = requests.get(
    f'https://api.thealert.io/api/v1/monitors/{MONITOR_ID}/checks',
    params={'limit': 500, 'since': since},
    headers={'Authorization': f'Bearer {API_KEY}'}
)
 
checks = response.json()['data']
 
with open('checks.csv', 'w', newline='') as f:
    writer = csv.DictWriter(f, fieldnames=['checkedAt', 'status', 'responseTime', 'statusCode', 'errorMessage'])
    writer.writeheader()
    writer.writerows(checks)
 
print(f'Exportados {len(checks)} checks')

Alimentar um dashboard externo

// Buscar dados para gráfico de latência (últimas 2 horas)
async function getLatencyData(monitorId) {
  const since = new Date(Date.now() - 2 * 60 * 60 * 1000).toISOString()
 
  const res = await fetch(
    `https://api.thealert.io/api/v1/monitors/${monitorId}/checks?limit=500&since=${since}`,
    { headers: { Authorization: `Bearer ${process.env.THEALERT_API_KEY}` } }
  )
 
  const { data } = await res.json()
 
  // Formatar para gráfico (ex: Chart.js)
  return data
    .filter(c => c.responseTime !== null)
    .map(c => ({
      x: new Date(c.checkedAt),
      y: c.responseTime
    }))
    .reverse() // ordem cronológica para o gráfico
}

Detectar períodos de downtime

from itertools import groupby
 
# Agrupa checks consecutivos por status
for status, group in groupby(checks, key=lambda c: c['status']):
    items = list(group)
    if status == 'DOWN':
        start = items[-1]['checkedAt']
        end = items[0]['checkedAt']
        print(f'Downtime: {start} → {end} ({len(items)} checks)')

Paginação

Para históricos muito longos, use since com timestamps incrementais para paginar:

# Página 1: últimas 500 checks
curl "https://api.thealert.io/api/v1/monitors/mon_abc123/checks?limit=500"
 
# Página 2: 500 checks anteriores ao mais antigo da página 1
# Use o checkedAt do último item retornado como novo "since" com lógica de cursor

O endpoint retorna checks em ordem decrescente (mais recente primeiro). O campo checkedAt do último item é o mais antigo do resultado.

Próximos passos

Monitores Status Pages