Monitores

Um monitor é uma consulta salva sobre um endpoint de dataset que a Croma avalia com uma frequência e envia por e-mail para até três endereços. Você descreve o que acompanhar do mesmo jeito que consultaria o endpoint; a Croma mantém o agendamento, lembra o que já reportou e envia só o que apareceu desde a última execução.

Monitores fazem parte da API. Crie-os com POST /monitors, pelo servidor MCP (create_monitor) ou pelo console em platform.usecroma.com/monitors. Os três administram os mesmos monitores.

Quais endpoints podem ser monitorados?

Todo endpoint que responde a partir de um dataset da Croma e pagina seus resultados. O catálogo os marca: GET /catalog devolve monitorable: true em cada um. Consultas ao vivo, que chegam à fonte na hora, ainda não podem ser monitoradas.

Criar um

curl -X POST https://api.croma.run/monitors \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contrato AD9-111",
    "endpoint": "/co/anm/notices-search/v1",
    "query": { "title_number": "AD9-111" },
    "schedule": { "cadence": "source" },
    "recipients": ["legal@example.com"],
    "notify": "always",
    "language": "es"
  }'

Campo	Significado
`endpoint`	O endpoint a acompanhar, por caminho ou por id de catálogo.
`query`	O corpo que o monitor envia em cada execução, validado exatamente como uma requisição direta. `page` e `per_page` não são permitidos.
`schedule`	Quando roda. Veja abaixo. Padrão `{ "cadence": "source" }`.
`recipients`	De um a três e-mails.
`notify`	`always` (padrão) envia um e-mail a cada execução, mesmo sem novidades; `on_new` só quando há algo a reportar.
`language`	`es` (padrão) ou `en`, para os e-mails.
`relevance`	Opcional. Uma instrução em linguagem natural que filtra os resultados novos antes do envio. Veja abaixo.

A resposta é o monitor com seu agendamento compilado:

{
  "data": {
    "id": "mon_5f1c2c0a-9d1e-4a3b-8c7d-1e2f3a4b5c6d",
    "name": "Contrato AD9-111",
    "endpoint": { "id": "anm-notices-search", "path": "/co/anm/notices-search/v1", "source": "ANM", "name": "Notices Search" },
    "query": { "title_number": "AD9-111" },
    "relevance": null,
    "schedule": { "cadence": "source", "timezone": "America/Bogota", "cron": "30 7 * * *", "next_run_at": "2026-09-22T12:30:00.000Z" },
    "recipients": ["legal@example.com"],
    "notify": "always",
    "language": "es",
    "status": "active",
    "created_at": "2026-09-21T15:04:05.000Z",
    "updated_at": "2026-09-21T15:04:05.000Z",
    "last_run": null
  }
}

A primeira execução

Logo após a criação, o monitor roda uma vez para registrar o que já coincide hoje (até 200 linhas) e envia um e-mail de boas-vindas com essa contagem e a próxima execução. Daí em diante, cada execução reporta apenas linhas nunca vistas.

Frequências

`cadence`	Roda
`source`	Logo depois que a atualização do próprio dataset termina. Em uma fonte diária, uma vez por dia, assim que os dados novos chegam.
`hourly`	A cada hora cheia.
`daily`	Todo dia às `at` (HH:MM, padrão 08:00) em `timezone` (padrão a do dataset).
`weekly`	Toda `weekday` (padrão monday) às `at`.

Um monitor nunca pode verificar uma fonte com mais frequência do que ela se atualiza: um dataset daily recusa hourly com schedule_faster_than_source. Quando uma execução source precisa seguir sem a atualização do dia (a fonte não publicou), a execução e seu e-mail dizem isso: source_stale é true e o e-mail diz “a fonte não publicou dados novos desde…”, nunca um simples “sem novidades”.

O filtro de relevância

Com relevance, cada linha nova é avaliada contra a sua instrução antes do envio. As linhas descartadas nunca se perdem: ficam no monitor com relevant: false e o e-mail diz quantas ficaram de fora. Se o filtro não estiver disponível, as linhas são enviadas marcadas como não revisadas em vez de descartadas.

{ "relevance": "solo avisos sobre suspensión o caducidad del título" }

GET /monitors/{id}/matches?relevant=false lista o que foi descartado, com o motivo de cada linha.

Administrar

Chamada	O que faz
`GET /monitors`	Seus monitores, com a última execução de cada um.
`GET /monitors/{id}`	Um monitor.
`PATCH /monitors/{id}`	Altera tudo menos o endpoint. `{ "status": "paused" }` pausa, `{ "status": "active" }` retoma.
`POST /monitors/{id}/run`	Roda agora, fora do agendamento.
`GET /monitors/{id}/runs`	Cada execução: quando, o que encontrou, se o e-mail saiu.
`GET /monitors/{id}/matches`	Cada linha reportada, com o veredito de relevância.
`DELETE /monitors/{id}`	Remove o monitor, seu agendamento, execuções e resultados.

Todo e-mail traz um link para parar de recebê-lo. Um monitor que fica sem destinatários é pausado.

Créditos e limites

Cada execução gasta os mesmos créditos que uma requisição ao endpoint (uma requisição de dataset). Criar e administrar monitores é grátis. Quando a organização fica sem créditos, a execução é registrada como skipped_plan_limit, os destinatários são avisados uma vez por dia e o agendamento se mantém. Uma organização pode ter até 20 monitores, cada um com até 3 destinatários. Uma execução reporta até 500 linhas novas; além disso fica marcada como truncated.

Primeiros passos

Tipos de solicitação

Países

Quais endpoints podem ser monitorados?

Criar um

A primeira execução

Frequências

O filtro de relevância

Administrar

Créditos e limites

​Quais endpoints podem ser monitorados?

​Criar um

​A primeira execução

​Frequências

​O filtro de relevância

​Administrar

​Créditos e limites

Quais endpoints podem ser monitorados?

Criar um

A primeira execução

Frequências

O filtro de relevância

Administrar

Créditos e limites