account/monitors

Creare un monitor e la prima baseline sono gratuiti. Un ciclo di 30 giorni viene addebitato non appena il monitor diventa attivo. Il prezzo dipende dall’intervallo di controllo e copre tutti i controlli che l’intervallo prevede in un ciclo.

Un intervallo tra due gradini costa quanto il gradino successivo più frequente: ogni quattro giorni costa quanto ogni tre giorni.

I controlli aggiuntivi avvengono soprattutto quando accorci l’intervallo a metà ciclo. Ogni controllo aggiuntivo riuscito costa l’importo indicato nella tabella.

Dopo 30 giorni il ciclo si rinnova automaticamente al prezzo valido in quel momento. I controlli non riusciti non costano nulla. Quando metti in pausa, archivi o cambi l’intervallo, non rimborsiamo nulla.

Ogni account può avere fino a 50 monitor contemporaneamente, uno per azienda. Entro 24 ore puoi creare fino a 50 monitor; contano anche quelli archiviati.

Il prezzo di un intervallo lo ottieni gratuitamente con GET /v1/account/monitoring/pricing, qui per un controllo ogni sette giorni:

1. Creare. Indichi l’azienda, l’intervallo di controllo e almeno un endpoint webhook verificato. Il monitor parte con lo stato initializing.
2. Baseline. Registriamo come noti i segnali degli ultimi giorni. Non vengono consegnati, così ricevi solo ciò che è nuovo da lì in poi.
3. Attivare. Addebitiamo il ciclo, il monitor diventa active e controlla subito per la prima volta.
4. Controllare. Poi controlla all’intervallo scelto. Ogni nuovo segnale genera un messaggio per monitor verso i tuoi endpoint webhook.
5. Rinnovare. Dopo ogni ciclo il successivo viene addebitato automaticamente, finché il tuo saldo lo copre.

L’intervallo di controllo è tra 1 e 30 giorni. Il momento esatto di un controllo può variare entro un’ora. Ogni controllo guarda indietro di qualche giorno, così arrivano anche le iscrizioni pubblicate in ritardo.

Un monitor consegna i temi Signals del tuo piano: cinque in ogni account, Insolvenze con Pro, Trasformazioni & M&A con Max. Un webhook porta lo stesso segnale nel campo data.signal come fa signals.

Per i monitor in pausa e gli errori, status_reason spiega il perché, ad esempio no_verified_endpoint o insufficient_cycle_floor.

Tutti i percorsi sono sotto /v1/account. Leggi e scrivi con la tua chiave API nell’header x-api-key.

Ogni richiesta di scrittura richiede l’header Idempotency-Key, un valore univoco per operazione, idealmente un UUID. Senza, l’API risponde con 428.

Se ripeti una richiesta con la stessa chiave e gli stessi dati entro 24 ore, ricevi la risposta salvata. Porta l’header Idempotency-Status: replayed. Così un errore di rete non crea un secondo monitor.

Vale anche per le risposte di errore. Per un nuovo tentativo dopo una correzione usa quindi una nuova chiave. La stessa chiave con dati diversi restituisce 409.

Sono ammessi fino a 128 caratteri: lettere, cifre e . _ : -. Il primo carattere è una lettera o una cifra. Una chiave in qualsiasi altro formato restituisce 400.

Ti servono l’entity_id dell’azienda e almeno un endpoint webhook verificato, vedi account/webhook-endpoints.

L’API risponde con 202: il monitor è creato, baseline e attivazione girano in background. meta.billing.charged_credits mostra che per questo non è stato addebitato nulla.

GET /v1/account/monitors restituisce fino a 100 monitor in monitors, con total. Quelli archiviati non sono nella lista.

GET /v1/account/monitors/{id} mostra anche il ciclo attuale in billing_cycle e gli ultimi controlli in recent_runs.

PATCH /v1/account/monitors/{id} cambia l’intervallo di controllo. Il controllo successivo segue allora il nuovo intervallo, contato dalla modifica.

Il ciclo attuale mantiene il suo prezzo e i controlli inclusi. Il nuovo prezzo vale dal ciclo successivo. Un intervallo più breve può generare controlli aggiuntivi nel ciclo attuale.

POST …/{id}/pause ferma un monitor attivo. Il ciclo pagato continua fino alla scadenza e non viene rimborsato nulla.

POST …/{id}/resume riprende un monitor in pausa o con un errore. Verifichiamo di nuovo endpoint webhook, saldo e prezzo.

All’interno del ciclo pagato in corso, riprendere non costa nulla. Se il ciclo è scaduto, parte ora un nuovo ciclo al prezzo attuale. meta.request_credit_cost mostra l’importo.

Se, ad esempio, manca un endpoint webhook verificato, l’API risponde comunque con 200, ma con meta.activated: false. Lo stato del monitor e status_reason indicano il motivo.

Se il prezzo è cambiato, un monitor attivo si ferma alla fine del ciclo con pricing_consent_required. Con resume accetti il nuovo prezzo.

DELETE …/{id} archivia il monitor definitivamente. È definitivo e non rimborsa nulla.

Gli errori hanno la struttura {"error": "…", "meta": {"message": "…"}}. Nel tuo programma controlla il valore di error. Il testo in meta.message è in inglese e può cambiare. Gli errori non costano nulla.