> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecroma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitores

> Acompanhe um endpoint de dataset com uma frequência e receba por e-mail o que é novo: como os monitores rodam após cada atualização da fonte, o que cobram, o filtro de relevância e a API completa.

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.

<Note>
  Monitores fazem parte da API. Crie-os com `POST /monitors`, pedindo ao Claude
  ou a qualquer cliente MCP ([Monitores pelo Claude](/pt/monitors-mcp)) ou pelo
  console em
  [platform.usecroma.com/monitors](https://platform.usecroma.com/monitors).
  Os três administram os mesmos monitores.
</Note>

## Quais endpoints podem ser monitorados?

Todo endpoint que responde a partir de um dataset da Croma e pagina seus
resultados: a lista está em [Fontes monitoráveis](/pt/monitors-sources), com o
nome da ferramenta e o horário de atualização de cada um. `GET /catalog` marca
os mesmos endpoints com `monitorable: true`. Consultas ao vivo, que chegam à
fonte na hora, ainda não podem ser monitoradas.

## Criar um

```bash theme={"dark"}
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, id de catálogo ou nome de ferramenta MCP (`anm_notices_search`).                                |
| `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:

```json theme={"dark"}
{
  "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.

```json theme={"dark"}
{ "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`.