Endpoint: Monitoraggio e Costi
Riferimento degli endpoint per l'utilizzo, i costi, gli allarmi e le dashboard di monitoraggio del tenant.
Tutte le richieste utilizzano l'URL base https://ai.askme.it/api/v2 e gli header descritti in Autenticazione (X-Api-Key, X-Source-App, X-External-Id opzionale).
I valori monetari (cost_usd) sono visibili solo ai profili con permesso adeguato; per gli altri ruoli sono restituiti azzerati (i conteggi di token e i record restano comunque accurati). La stessa regola di visibilità per ruolo si applica sia in console sia tramite queste API.
1. Utilizzo
GET /usage
Elenca i record di utilizzo del tenant.
Attributi richiesta
| Campo | In | Tipo | Default | Descrizione |
|---|---|---|---|---|
start_time | query | datetime ISO 8601 | — | Inizio finestra. |
end_time | query | datetime ISO 8601 | — | Fine finestra. |
service | query | string | — | Filtra per servizio (es. ai-core, knowledge). |
offset, limit | query | int | 0, 100 | Paginazione (limit max 1000). |
Esempio risposta (200 OK)
{
"items": [
{
"id": 9001,
"tenant_id": "acme",
"service": "ai-core",
"resource": "chat",
"operation": "message",
"quantity": 1,
"unit": "message",
"metadata": { "agent_id": 87 },
"timestamp": "2026-04-30T11:22:14Z"
}
],
"total": 1,
"offset": 0,
"limit": 100
}
GET /usage/stats
Statistiche aggregate di utilizzo per il periodo richiesto (stessi filtri di GET /usage).
2. Costi
GET /costs/summary
Sintesi costi del periodo, con breakdown per servizio, modello, operazione, source app, cost tier e giorno.
Attributi richiesta
| Campo | In | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|---|
start_time | query | datetime ISO 8601 | Sì | Inizio finestra. |
end_time | query | datetime ISO 8601 | Sì | Fine finestra. |
service | query | string | No | Filtro. |
model | query | string | No | Filtro. |
source_app | query | string | No | Filtro. |
operation_type | query | string | No | Filtro su metadata.operation_type. |
cost_tier | query | string | No | Filtro. |
Esempio richiesta
curl -G "https://ai.askme.it/api/v2/costs/summary" \
-H "X-Api-Key: amai_xxxxxxxxxxxxxxxx" \
-H "X-Source-App: api_direct" \
--data-urlencode "start_time=2026-04-01T00:00:00Z" \
--data-urlencode "end_time=2026-04-30T23:59:59Z"
Esempio risposta (200 OK)
{
"tenant_id": "acme",
"start_time": "2026-04-01T00:00:00Z",
"end_time": "2026-04-30T23:59:59Z",
"total_cost_usd": "12.4810",
"total_input_tokens": 412300,
"total_output_tokens": 88142,
"by_service": [
{ "key": "ai-core", "total_cost_usd": "10.20", "total_input_tokens": 320000, "total_output_tokens": 64000, "record_count": 1102 }
],
"by_model": [
{ "key": "gpt-4o-mini", "total_cost_usd": "8.10", "total_input_tokens": 290000, "total_output_tokens": 60000, "record_count": 980 }
],
"by_operation_type": [
{ "key": "chat.generation", "total_cost_usd": "9.40", "total_input_tokens": 300000, "total_output_tokens": 70000, "record_count": 950 }
],
"by_source_app": [
{ "key": "api_direct", "total_cost_usd": "5.20", "total_input_tokens": 150000, "total_output_tokens": 30000, "record_count": 410 }
],
"by_date": [
{ "date": "2026-04-01", "total_cost_usd": "0.42", "total_input_tokens": 11200, "total_output_tokens": 2820 }
]
}
GET /costs/by-category
Breakdown costi per operation_type (es. chat.generation, chat.query_rewrite, chat.rerank, analysis.pdf, ecc.).
Attributi richiesta: start_time, end_time (entrambi obbligatori).
Esempio risposta (200 OK)
[
{ "key": "chat.generation", "total_cost_usd": 9.40, "total_input_tokens": 300000, "total_output_tokens": 70000, "record_count": 950 },
{ "key": "chat.query_rewrite", "total_cost_usd": 0.20, "total_input_tokens": 8000, "total_output_tokens": 1200, "record_count": 410 },
{ "key": "unknown", "total_cost_usd": 0.00, "total_input_tokens": 1200, "total_output_tokens": 200, "record_count": 12 }
]
I record privi del tag finiscono nel bucket unknown.
Endpoint analoghi, stessa struttura di risposta: GET /costs/by-service, GET /costs/by-model, GET /costs/by-source-app, GET /costs/by-cost-tier.
GET /costs
Lista paginata dei singoli record di costo con filtri estesi (service, model, source_app, operation_type, cost_tier, conversation_id, turn_id, external_id, agent_id, is_streaming).
GET /costs/conversations/{conversation_id}/turns
Riepilogo costi per ogni turn della conversazione.
GET /costs/turns/{turn_id}/events
Tutti gli eventi di costo di un singolo turn (utile per audit dettagliato).
GET /costs/export
Esportazione dei record di costo del periodo richiesto (stessi filtri di GET /costs).
DELETE /costs/by-conversation/{id}
Cancellazione dei record di costo associati a una conversazione, a supporto delle richieste di cancellazione dati (GDPR).
3. Dashboard
GET /dashboard/metrics
Metriche aggregate per la dashboard (cache di circa 2 secondi).
Esempio risposta (200 OK)
{
"conversationsToday": 142,
"conversationsChange": 8.2,
"activeAgents": 12,
"activeAgentsChange": 0.0,
"knowledgeBases": 6,
"mtdCost": 4.81,
"mtdCostChange": -3.4,
"handoffsToday": 4,
"handoffsChange": 33.3,
"quotaUsagePercent": 42.0,
"quotaUsageChange": 5.1,
"isSuperAdmin": false
}
GET /dashboard/trend
Trend conversazioni per giorno (parametro days, default 30).
GET /dashboard/top-agents
Classifica degli agenti per volume di conversazioni.
Dashboard personalizzate
Riferimento sintetico derivato dall'inventario delle funzionalità; parametri di dettaglio ed esempi saranno aggiunti in un aggiornamento successivo.
| Endpoint | Metodo | Descrizione |
|---|---|---|
/dashboards | GET, POST, PUT, DELETE | Gestione delle dashboard personalizzate del tenant. |
/dashboards/default | GET | Dashboard predefinita del tenant. |
4. Monitoraggio dettagliato
Riferimento sintetico derivato dall'inventario delle funzionalità; parametri di dettaglio ed esempi saranno aggiunti in un aggiornamento successivo.
| Endpoint | Metodo | Descrizione |
|---|---|---|
/monitoring/overview | GET | Vista di sintesi su conversazioni, costi e handoff del tenant. |
/monitoring/costs | GET | Vista costi orientata al monitoraggio (complementare a /costs/summary). |
/monitoring/timeline/{conversation_id} | GET | Timeline degli eventi di una conversazione. |
/monitoring/rag-traces/{turn_id} | GET | Traccia dettagliata del retrieval RAG per un turno di conversazione. |
5. Allarmi
Riferimento sintetico derivato dall'inventario delle funzionalità; parametri di dettaglio ed esempi saranno aggiunti in un aggiornamento successivo.
| Endpoint | Metodo | Descrizione |
|---|---|---|
/alerts/rules | GET, POST, PUT, DELETE | Regole di allarme (es. soglia di costo o di errore superata). |
/alerts/events | GET | Eventi di allarme generati. |
/alerts/evaluate | POST | Forza la valutazione delle regole di allarme configurate. |
6. Log e metriche operative
POST /logs/client
Raccoglie log di errore lato client per la diagnosi.
GET /metrics
Metriche Prometheus in formato testo (text/plain). Endpoint operativo, generalmente consumato dal sistema di monitoring infrastrutturale.