Referência da API de monitores

Valores possíveis dos campos

Local do monitor

ValorDescrição
US_EAST_1Norte da Virgínia
CA_CENTRAL_1Canadá (Montreal)
EU_CENTRAL_1Frankfurt
AP_NORTHEAST_1Tóquio

Tipos de alerta do monitor

ValorDescrição
INCIDENTAlerta de incidente
EMAILAlerta por e-mail
SMSAlerta por SMS
SLACKAlerta pelo Slack
DISCORDAlerta pelo Discord
MICROSOFT_TEAMSAlerta pelo Microsoft Teams
PHONE_CALLAlerta por ligação
WEBHOOKAlerta por webhook
GOOGLE_CHATAlerta pelo Google Chat
WHATSAPPAlerta pelo WhatsApp

Status do monitor

ValorDescrição
UPO monitor está rodando normalmente
DOWNO monitor falhou
DEGRADEDO monitor está com problemas
UNKNOWNNã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âmetroTipoValor padrãoDescrição
pagenumber1O número da página a buscar.
limitnumber100Quantidade de monitores por página.
searchstringnullTermo de busca para filtrar os resultados.
statusenumnullFiltro 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âmetroTipoValor padrãoDescrição
limitnumber100Quantidade de itens por página. Não pode passar de 1000.
pagenumber1O número da página a buscar.
monitorIdstring-O ID do monitor.
locationstringnullO local do monitor.
createdAtstring | object | numbernullA data de criação. Pode ser uma string, um número ou um objeto com os campos gte e lte.
isSuccessfulbooleannullSe a verificação teve sucesso.
isSSLCheckbooleannullSe a verificação é uma verificação de SSL.
httpStatusCodestringnullO código de status HTTP da resposta.
status('UP', 'DOWN', 'UNKNOWN', 'DEGRADED')nullO status do monitor.
dnsTimestring | number | objectnullTempo gasto na resolução de DNS.
tcpTimestring | number | objectnullTempo gasto na conexão TCP.
tlsTimestring | number | objectnullTempo gasto no handshake TLS.
firstByteTimestring | number | objectnullTempo até o primeiro byte ser recebido.
downloadTimestring | number | objectnullTempo gasto no download.
responseTimestring | number | objectnullTempo total de resposta.
performanceTimestring | number | objectnullTempo de desempenho.
accessabilityScorestring | number | objectnullPontuação de acessibilidade.
seoScorestring | number | objectnullPontuação de SEO.
bestPracticesScorestring | number | objectnullPontuação de boas práticas.
successfulAssertionsstring | number | objectnullNúmero de asserções bem-sucedidas.
sortstringcronologicamenteCampo 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âmetroTipoValor padrãoDescriçã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.
retrybooleanfalseIndica se a operação deve ser repetida. Opcional.
monitorLogIdstringnullO 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âmetroTipoValor padrãoDescrição
limitnumber100Quantidade de itens por página.
pagenumber1O 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âmetroTipoValor padrãoDescriçã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.
retrybooleanfalseIndica se a operação deve ser repetida. Opcional.
monitorLogIdstringnullO 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

ValorDescrição
UPO monitor está rodando normalmente
DOWNO monitor falhou
DEGRADEDO monitor está com problemas
UNKNOWNNão dá para determinar o estado do monitor

Estado do monitor cron

ValorDescrição
ACTIVEO monitor é verificado ativamente
PAUSEDAs verificações estão pausadas
MUTEDO monitor está silenciado (sem notificações)

Status do registro do monitor cron

ValorDescrição
SUCCESSA tarefa foi concluída com sucesso
FAILUREA tarefa reportou uma falha explicitamente
MISSEDA tarefa não enviou ping na janela esperada
LATEA tarefa enviou ping após o período, mas dentro da tolerância
STARTEDA 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âmetroTipoValor padrãoDescrição
limitnumber100Quantidade de monitores cron por página. O máximo é 100.
pagenumber1O número da página.
searchstringnullTermo de busca para filtrar os resultados por nome.
statusenumnullFiltro 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âmetroTipoValor padrãoDescrição
limitnumber100Quantidade de registros por página. O máximo é 127.
pagenumber1O número da página. O máximo é 1000.
startDatestring1 ano atrásData inicial em ISO 8601 do intervalo de registros.
endDatestringagoraData final em ISO 8601 do intervalo de registros.
importanceenumnullFiltra 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} ou GET / POST / HEAD /monitors/cron/{slug}
  • Falha: https://cron.instatus.com/{slug}/fail ou GET / POST / HEAD /monitors/cron/{slug}/fail
  • Início: https://cron.instatus.com/{slug}/start ou GET / 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"
}