# AI Usage Tracking & Cost Monitoring

**Document Version:** 1.0.0 (Phase 12)

---

## 1. Usage Metric Logging

Every AI qualification operation records a row in `ai_usage_logs`:

| Column | Description |
|--------|-------------|
| `workspace_id` | Multi-tenant workspace reference |
| `lead_id` | Associated lead reference (nullable) |
| `provider` | Provider string (e.g. `openai-gpt4o-mini`, `fallback_rules`) |
| `tokens_prompt` | Estimated prompt tokens |
| `tokens_completion` | Estimated completion tokens |
| `tokens_total` | Total tokens consumed |
| `estimated_cost_usd` | Estimated USD API cost |
| `execution_ms` | Request latency in milliseconds |
| `status` | `success`, `fallback`, `timeout`, or `error` |

---

## 2. Cost Control & Rate Limiting

- **Workspace Toggle:** Workspaces can disable AI qualification or switch to manual-only evaluation in `/settings/ai`.
- **Throttling:** Manual qualification requests are capped at 10 requests per minute per user/IP.