Referência da API de monitores
Valores possíveis dos campos
Local do monitor
| Valor | Descrição |
|---|---|
US_EAST_1 | Norte da Virgínia |
CA_CENTRAL_1 | Canadá (Montreal) |
EU_CENTRAL_1 | Frankfurt |
AP_NORTHEAST_1 | Tóquio |
Tipos de alerta do monitor
| Valor | Descrição |
|---|---|
INCIDENT | Alerta de incidente |
EMAIL | Alerta por e-mail |
SMS | Alerta por SMS |
SLACK | Alerta pelo Slack |
DISCORD | Alerta pelo Discord |
MICROSOFT_TEAMS | Alerta pelo Microsoft Teams |
PHONE_CALL | Alerta por ligação |
WEBHOOK | Alerta por webhook |
GOOGLE_CHAT | Alerta pelo Google Chat |
WHATSAPP | Alerta pelo WhatsApp |
Status do monitor
| Valor | Descrição |
|---|---|
UP | O monitor está rodando normalmente |
DOWN | O monitor falhou |
DEGRADED | O monitor está com problemas |
UNKNOWN | Não dá para determinar o estado do monitor |
Obter os monitores
Use este endpoint para percorrer a lista de todos os monitores existentes.
Endpoint:
GET /:page_id/monitors
Parâmetros de query
| Parâmetro | Tipo | Valor padrão | Descrição |
|---|---|---|---|
page | number | 1 | O número da página a buscar. |
limit | number | 100 | Quantidade de monitores por página. |
search | string | null | Termo de busca para filtrar os resultados. |
status | enum | null | Filtro de status ('UP', 'DOWN', 'UNKNOWN', 'DEGRADED'). |
Exemplo de requisição
GET /1/monitors?limit=3&page=2&status=DOWN
Exemplo de resposta
{"monitors": [{ "...": "monitor objects" }],"total": 10,"page": 3,"totalPages": 5,"limit": 2}
Criar um monitor
Endpoint:
POST /monitors
Exemplo de requisição
{"pageId": "page123","url": "https://example.com","httpMethod": "GET","body": null,"headers": {"Content-Type": "application/json","Authorization": "Bearer token"},"queryParams": {"search": "test","limit": "10"},"basicAuth": {"username": "user","password": "password"},"type": "HTTP","assertions": [{"type": "STATUSCODE","comparison": "EQUALS","selector": null,"target": "200"}],"alerts": ["alert-id-1", "alert-id-2"],"name": "Example Monitor","locations": "US_EAST_1","checksInterval": 300,"createComponent": true,"createMetric": true,"onFail": {"createIncident": true,"createOutageDuration": true,"publishIncident": true,"notifySubscribers": true},"onRecover": {"resolveIncident": true,"resolveOutageDuration": true,"publishIncident": true,"notifySubscribers": true}}
Exemplo de resposta
{"monitor": {"pageId": "page123","url": "https://example.com","httpMethod": "GET","body": null,"headers": {"Content-Type": "application/json","Authorization": "Bearer token"},"queryParams": {"search": "test","limit": "10"},"basicAuth": {"username": "user","password": "password"},"type": "HTTP","assertions": [{"id": "assertion1","type": "STATUSCODE","comparison": "EQUALS","selector": null,"target": "200"}],"alerts": ["alert1", "alert2"],"name": "Example Monitor","locations": "US_EAST_1","checksInterval": 300,"createComponent": true,"createMetric": true,"onFail": {"createIncident": true,"createOutageDuration": true,"publishIncident": true,"notifySubscribers": true},"onRecover": {"resolveIncident": true,"resolveOutageDuration": true,"publishIncident": true,"notifySubscribers": true},"createdAt": "2023-08-08T12:00:00Z","updatedAt": "2023-08-08T12:00:00Z"},"message": "Monitor created successfully"}
Atualizar um monitor
Endpoint:
PUT /monitors/:id
Exemplo de requisição
{"url": "https://updated.com","name": "Updated Monitor Name"}
Exemplo de resposta
{"monitor": {"pageId": "page123","url": "https://updated.com","httpMethod": "GET","body": null,"headers": {"Content-Type": "application/json","Authorization": "Bearer token"},"queryParams": {"search": "test","limit": "10"},"basicAuth": {"username": "user","password": "password"},"type": "HTTP","assertions": [{"id": "assertion1","type": "STATUSCODE","comparison": "EQUALS","selector": null,"value": "200"}],"alerts": ["alert1", "alert2"],"name": "Updated Monitor Name","locations": "US_EAST_1","checksInterval": 300,"createComponent": true,"createMetric": true,"onFail": {"createIncident": true,"createOutageDuration": true,"publishIncident": true,"notifySubscribers": true},"onRecover": {"resolveIncident": true,"resolveOutageDuration": true,"publishIncident": true,"notifySubscribers": true},"createdAt": "2023-08-08T12:00:00Z","updatedAt": "2023-08-08T12:00:00Z"},"message": "Monitor updated successfully"}
Excluir um monitor
Endpoint:
DELETE /monitors/:id
Exemplo de requisição
DELETE /monitors/monitor-id-1
Exemplo de resposta
{"message": "Monitor deleted successfully."}
Obter os registros do monitor
Endpoint:
GET /monitors/:id/logs
Parâmetros de query
| Parâmetro | Tipo | Valor padrão | Descrição |
|---|---|---|---|
limit | number | 100 | Quantidade de itens por página. Não pode passar de 1000. |
page | number | 1 | O número da página a buscar. |
monitorId | string | - | O ID do monitor. |
location | string | null | O local do monitor. |
createdAt | string | object | number | null | A data de criação. Pode ser uma string, um número ou um objeto com os campos gte e lte. |
isSuccessful | boolean | null | Se a verificação teve sucesso. |
isSSLCheck | boolean | null | Se a verificação é uma verificação de SSL. |
httpStatusCode | string | null | O código de status HTTP da resposta. |
status | ('UP', 'DOWN', 'UNKNOWN', 'DEGRADED') | null | O status do monitor. |
dnsTime | string | number | object | null | Tempo gasto na resolução de DNS. |
tcpTime | string | number | object | null | Tempo gasto na conexão TCP. |
tlsTime | string | number | object | null | Tempo gasto no handshake TLS. |
firstByteTime | string | number | object | null | Tempo até o primeiro byte ser recebido. |
downloadTime | string | number | object | null | Tempo gasto no download. |
responseTime | string | number | object | null | Tempo total de resposta. |
performanceTime | string | number | object | null | Tempo de desempenho. |
accessabilityScore | string | number | object | null | Pontuação de acessibilidade. |
seoScore | string | number | object | null | Pontuação de SEO. |
bestPracticesScore | string | number | object | null | Pontuação de boas práticas. |
successfulAssertions | string | number | object | null | Número de asserções bem-sucedidas. |
sort | string | cronologicamente | Campo pelo qual ordenar. |
Exemplo de requisição
GET /monitors/monitor-id-1/logs?limit=100&page=1
Exemplo de resposta
{"monitorLogs": [// {monitor log object},// {monitor log object 2}],"total": 478,"page": 1,"totalPages": 5,"limit": 100}
Rodar a verificação de um monitor por ID
Endpoint:
GET /monitors/:id/run
Parâmetros de query
| Parâmetro | Tipo | Valor padrão | Descrição |
|---|---|---|---|
location | 'US_EAST_1', 'EU_CENTRAL_1', 'AP_NORTHEAST_1', 'AP_SOUTHEAST_2', 'CA_CENTRAL_1' | - | O local do monitor. Precisa ser um dos valores indicados. |
retry | boolean | false | Indica se a operação deve ser repetida. Opcional. |
monitorLogId | string | null | O identificador único do registro do monitor. Opcional. |
Exemplo de requisição
GET /monitors/monitor-id-1/run?monitorId=abc123&location=US_EAST_1&retry=true&monitorLogId=log456
Exemplo de resposta
{"status": "success","message": "Monitor check run successfully."}
Criar alerta de monitor
Endpoint:
POST /monitor-alerts
Exemplo de requisição
{"type": "EMAIL","pageId": "page123","recipient": "user@example.com","recipientWorkspace": "workspace123","whenFails": true,"whenRecovers": true,"whenDegrades": false,"whenSslExpires": true,"sslExpiresInDays": 30,"monitors": ["monitor1", "monitor2"],"metadata": "Additional information about the alert"}
Exemplo de resposta
{"monitor": {"id": "alert123","siteId": "site123","type": "EMAIL","recipient": "user@example.com","whenFails": true,"whenRecovers": true,"whenDegrades": false,"whenSslExpires": true,"sslExpiresInDays": 30,"monitors": [{ "id": "monitor1" }, { "id": "monitor2" }],"createdAt": "2023-08-08T12:00:00Z","updatedAt": "2023-08-08T12:00:00Z","metadata": "Additional information about the alert"},"message": "Monitor Alert created successfully"}
Atualizar alerta de monitor
Endpoint:
PUT /monitor-alerts/:id
Exemplo de requisição
{"type": "EMAIL","monitors": ["monitor-1-id", "monitor-2-id", "monitor-3-id"]}
Exemplo de resposta
{"monitor": {"type": "EMAIL","pageId": "page123","recipient": "user@example.com","recipientWorkspace": "workspace123","whenFails": true,"whenRecovers": true,"whenDegrades": false,"whenSslExpires": true,"sslExpiresInDays": 30,"monitors": ["monitor-1-id", "monitor-2-id"],"metadata": "Additional information about the alert"},"message": "Monitor alert updated successfully."}
Obter os alertas do monitor
Endpoint:
GET /:page_id/monitor-alerts
Parâmetros de query
| Parâmetro | Tipo | Valor padrão | Descrição |
|---|---|---|---|
limit | number | 100 | Quantidade de itens por página. |
page | number | 1 | O número da página a buscar. |
Exemplo de requisição
GET /1/monitor-alerts?limit=2&page=3
Exemplo de resposta
{"monitorAlerts": [{...monitor alert objects}],"total": 27,"page": 3,"totalPages": 14,"limit": 2}
Excluir alerta de monitor
Endpoint:
DELETE /monitor-alerts/:id
Exemplo de requisição
DELETE /monitor-alerts/alert-id-1
Exemplo de resposta
{"message": "Monitor alert deleted successfully."}
Criar grupo de monitores
Endpoint:
POST /monitors-groups
Exemplo de requisição
{"pageId": "page123","name": "Example Name","childId": "child456"}
Exemplo de resposta
{"monitor": {"id": "group123","name": "Example Name","siteId": "site123","collapsed": false,"monitors": [{ "id": "monitor1" }, { "id": "monitor2" }],"groupId": "parentGroup123","children": [{ "id": "childGroup1", "name": "Child Group 1" },{ "id": "childGroup2", "name": "Child Group 2" }],"order": 1,"createdAt": "2023-08-08T12:00:00Z","updatedAt": "2023-08-08T12:00:00Z","parents": ["parent1", "parent2"],"componentId": "component123"},"message": "Monitor group created successfully."}
Atualizar grupo de monitores
Endpoint:
PUT /monitors-groups/:id
Exemplo de requisição
{"name": "Updated Monitor Group Name"}
Exemplo de resposta
{"monitor": {"id": "group123","name": "Updated Monitor Group Name","siteId": "site123","collapsed": true,"monitors": [{ "id": "monitor1" }, { "id": "monitor2" }],"groupId": "parentGroup123","children": [{ "id": "childGroup1", "name": "Child Group 1" },{ "id": "childGroup2", "name": "Child Group 2" }],"order": 1,"createdAt": "2023-08-08T12:00:00Z","updatedAt": "2023-08-08T12:00:00Z","parents": ["parent1", "parent2"],"componentId": "component123"},"message": "Monitor group updated successfully."}
Excluir grupo de monitores
Endpoint:
DELETE /monitors-groups/:id
Exemplo de requisição
DELETE /monitors-groups/group-id-1
Exemplo de resposta
{"message": "Monitor group deleted successfully."}
Adicionar monitores a um grupo
Endpoint:
POST /monitors-groups/:id/monitors
Exemplo de requisição
{"monitors": ["monitor1", "monitor2", "monitor3"]}
Exemplo de resposta
{"message": "Monitors added to the group successfully."}
Rodar a verificação de um grupo de monitores
Endpoint:
GET /monitors-groups/:id/run
Parâmetros de query
| Parâmetro | Tipo | Valor padrão | Descrição |
|---|---|---|---|
location | 'US_EAST_1', 'EU_CENTRAL_1', 'AP_NORTHEAST_1', 'AP_SOUTHEAST_2', 'CA_CENTRAL_1' | - | O local do monitor. Precisa ser um dos valores indicados. |
retry | boolean | false | Indica se a operação deve ser repetida. Opcional. |
monitorLogId | string | null | O identificador único do registro do monitor. Opcional. |
Exemplo de requisição
GET /monitors-groups/group-id-1/run
Exemplo de resposta
{"result": "OK","monitorLogId": "monitor-log-id-1"}
Monitores cron
Monitores cron acompanham tarefas agendadas por meio de pings HTTP. Para a configuração no produto e o uso no painel, veja Monitoramento cron.
Valores possíveis dos campos
Status do monitor cron
| Valor | Descrição |
|---|---|
UP | O monitor está rodando normalmente |
DOWN | O monitor falhou |
DEGRADED | O monitor está com problemas |
UNKNOWN | Não dá para determinar o estado do monitor |
Estado do monitor cron
| Valor | Descrição |
|---|---|
ACTIVE | O monitor é verificado ativamente |
PAUSED | As verificações estão pausadas |
MUTED | O monitor está silenciado (sem notificações) |
Status do registro do monitor cron
| Valor | Descrição |
|---|---|
SUCCESS | A tarefa foi concluída com sucesso |
FAILURE | A tarefa reportou uma falha explicitamente |
MISSED | A tarefa não enviou ping na janela esperada |
LATE | A tarefa enviou ping após o período, mas dentro da tolerância |
STARTED | A tarefa informou que começou (medição de execução) |
Período e tolerância
Tanto period quanto grace são informados em segundos. period é a frequência com que a tarefa deve rodar; grace é o tempo extra permitido antes de o monitor ser marcado como fora do ar.
Obter os monitores cron
Endpoint:
GET /:page_id/monitors/cron
Parâmetros de query
| Parâmetro | Tipo | Valor padrão | Descrição |
|---|---|---|---|
limit | number | 100 | Quantidade de monitores cron por página. O máximo é 100. |
page | number | 1 | O número da página. |
search | string | null | Termo de busca para filtrar os resultados por nome. |
status | enum | null | Filtro de status ('UP', 'DOWN', 'UNKNOWN', 'DEGRADED'). |
Exemplo de requisição
GET /page123/monitors/cron?limit=10&page=1&status=DOWN
Exemplo de resposta
{"cronMonitors": [{"id": "cron-abc123","name": "Daily backup","slug": "my-page-x7k2m9n4p1q8w3e5","period": 86400,"grace": 3600,"status": "UP","state": "ACTIVE","siteId": "page123","order": 1,"groupId": null,"componentId": "component-id-1","onFailCreateIncident": true,"onFailCreateOutageDuration": false,"onFailPublishIncident": true,"onFailNotifySubscribers": true,"onRecoverResolveIncident": true,"onRecoverResolveOutageDuration": false,"onRecoverPublishIncident": true,"onRecoverNotifySubscribers": true,"createTemplateId": null,"resolveTemplateId": null,"createdAt": "2024-01-15T08:00:00.000Z","updatedAt": "2024-01-15T08:00:00.000Z"}],"total": 1,"page": 1,"totalPages": 1,"limit": 10}
Criar um monitor cron
Endpoint:
POST /monitors/cron
Exemplo de requisição
{"pageId": "page123","name": "Daily backup","period": 86400,"grace": 3600,"alerts": ["alert-id-1", "alert-id-2"],"createComponent": true,"onFail": {"createIncident": true,"createOutageDuration": false,"publishIncident": true,"notifySubscribers": true},"onRecover": {"resolveIncident": true,"resolveOutageDuration": false,"publishIncident": true,"notifySubscribers": true}}
Exemplo de resposta
{"cronMonitor": {"id": "cron-abc123","name": "Daily backup","slug": "my-page-x7k2m9n4p1q8w3e5","period": 86400,"grace": 3600,"status": "UP","state": "ACTIVE","siteId": "page123","order": 1,"groupId": null,"componentId": "component-id-1","onFailCreateIncident": true,"onFailCreateOutageDuration": false,"onFailPublishIncident": true,"onFailNotifySubscribers": true,"onRecoverResolveIncident": true,"onRecoverResolveOutageDuration": false,"onRecoverPublishIncident": true,"onRecoverNotifySubscribers": true,"createTemplateId": null,"resolveTemplateId": null,"createdAt": "2024-01-15T08:00:00.000Z","updatedAt": "2024-01-15T08:00:00.000Z"},"message": "Cron monitor created successfully."}
A resposta inclui um slug. Use-o para montar as URLs de ping da sua tarefa. O primeiro ping bem-sucedido agenda a verificação em segundo plano.
Atualizar um monitor cron
Endpoint:
PUT /monitors/cron/:id
Exemplo de requisição
{"name": "Daily backup (updated)","period": 43200,"grace": 1800,"state": "PAUSED","alerts": ["alert-id-1"],"onFail": {"notifySubscribers": false}}
Exemplo de resposta
{"cronMonitor": {"id": "cron-abc123","name": "Daily backup (updated)","slug": "my-page-x7k2m9n4p1q8w3e5","period": 43200,"grace": 1800,"status": "UP","state": "PAUSED","siteId": "page123","order": 1,"groupId": null,"componentId": "component-id-1","onFailCreateIncident": true,"onFailCreateOutageDuration": false,"onFailPublishIncident": true,"onFailNotifySubscribers": false,"onRecoverResolveIncident": true,"onRecoverResolveOutageDuration": false,"onRecoverPublishIncident": true,"onRecoverNotifySubscribers": true,"createTemplateId": null,"resolveTemplateId": null,"alerts": [{"id": "alert-id-1","type": "EMAIL","recipient": "ops@example.com"}],"createdAt": "2024-01-15T08:00:00.000Z","updatedAt": "2024-01-16T10:30:00.000Z"},"message": "Cron monitor updated successfully."}
Excluir um monitor cron
Endpoint:
DELETE /monitors/cron/:id
Exemplo de requisição
DELETE /monitors/cron/cron-abc123
Exemplo de resposta
{"cronMonitor": {"id": "cron-abc123","name": "Daily backup","slug": "my-page-x7k2m9n4p1q8w3e5","period": 86400,"grace": 3600,"status": "UP","state": "ACTIVE","siteId": "page123","order": 1,"groupId": null,"componentId": "component-id-1","onFailCreateIncident": true,"onFailCreateOutageDuration": false,"onFailPublishIncident": true,"onFailNotifySubscribers": true,"onRecoverResolveIncident": true,"onRecoverResolveOutageDuration": false,"onRecoverPublishIncident": true,"onRecoverNotifySubscribers": true,"createTemplateId": null,"resolveTemplateId": null,"createdAt": "2024-01-15T08:00:00.000Z","updatedAt": "2024-01-15T08:00:00.000Z"},"message": "Cron monitor deleted successfully."}
Obter os registros do monitor cron
Endpoint:
GET /monitors/cron/:id/logs
Parâmetros de query
| Parâmetro | Tipo | Valor padrão | Descrição |
|---|---|---|---|
limit | number | 100 | Quantidade de registros por página. O máximo é 127. |
page | number | 1 | O número da página. O máximo é 1000. |
startDate | string | 1 ano atrás | Data inicial em ISO 8601 do intervalo de registros. |
endDate | string | agora | Data final em ISO 8601 do intervalo de registros. |
importance | enum | null | Filtra os registros por importância ('all', 'important'). |
Exemplo de requisição
GET /monitors/cron/cron-abc123/logs?limit=50&page=1&importance=important
Exemplo de resposta
{"logs": [{"id": "log-xyz789","monitorId": "cron-abc123","status": "SUCCESS","requestType": "GET","agent": "curl/8.4.0","ipAddress": "203.0.113.10","createdAt": "2024-01-16T06:00:00.000Z","startedAt": "2024-01-16T05:59:58.000Z"}],"page": 1}
Obter o resumo do monitor cron
Endpoint:
GET /monitors/cron/:id/summary
Exemplo de requisição
GET /monitors/cron/cron-abc123/summary
Exemplo de resposta
{"summary": {"totalLogs": 120,"totalFailedLogs": 3,"availability": 97.5,"oneDayAvailability": 100,"previousDayAvailability": 100,"sevenDayAvailability": 98.2,"previousSevenDayAvailability": 96.1,"thirtyDayAvailability": 97.5,"previousThirtyDayAvailability": 95.8,"lastSuccess": "2024-01-16T06:00:00.000Z","lastFailure": "2024-01-10T06:00:00.000Z","lastStarted": null,"upSince": "2024-01-10T07:00:00.000Z","downSince": null}}
Endpoints de ping
Estes endpoints não exigem autenticação. O slug do monitor funciona como segredo.
Você pode enviar o ping pela URL base da API ou pelo host dedicado de cron:
- Sucesso:
https://cron.instatus.com/{slug}ouGET/POST/HEAD/monitors/cron/{slug} - Falha:
https://cron.instatus.com/{slug}/failouGET/POST/HEAD/monitors/cron/{slug}/fail - Início:
https://cron.instatus.com/{slug}/startouGET/POST/HEAD/monitors/cron/{slug}/start
Envie um ping de sucesso sempre que sua tarefa terminar no horário. Envie um ping de início antes de a tarefa rodar e um ping de sucesso ou falha quando ela terminar para registrar o tempo de execução.
Exemplo de ping de sucesso
curl https://cron.instatus.com/my-page-x7k2m9n4p1q8w3e5
Exemplo de resposta
{"id": "log-xyz789","monitorId": "cron-abc123","status": "SUCCESS","requestType": "GET","agent": "curl/8.4.0","ipAddress": "203.0.113.10","createdAt": "2024-01-16T06:00:00.000Z"}
Se o slug for inválido, a resposta é:
{"message": "Monitor not found"}