Align all API docs with edge function implementations

api-reference/analytics.mdx

@@ -1,82 +1,137 @@
 ---
 title: "Analytics"
 sidebarTitle: "GET /v1/analytics"
-description: "Aggregated analytics on comment trends, sentiment shifts, and engagement patterns."
+description: "Aggregated API usage analytics including request counts, costs, cache rates, and latency."
 api: "GET https://api.trynawa.com/v1/analytics"
 ---
 
-Retrieve aggregated analytics across your classified comments. This endpoint is **free**.
+Retrieve aggregated analytics for your API usage. Returns request counts, costs, cache hit rates, latency, success rates, and breakdowns grouped by endpoint, day, or provider. This endpoint is **free**.
 
 ## Request
 
 ### Query parameters
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `channel_id` | string | No | Filter by channel ID |
-| `platform` | string | No | Filter by platform |
-| `from` | string | No | Start date (ISO 8601) |
-| `to` | string | No | End date (ISO 8601) |
-| `group_by` | string | No | Group results by: `day`, `week`, `month`. Default: `day`. |
+| `from` | string | No | Start date (ISO 8601). Filters usage logs from this date. |
+| `to` | string | No | End date (ISO 8601). Filters usage logs up to this date. |
+| `group_by` | string | No | Group breakdown by: `endpoint`, `day`, `provider`. Default: `endpoint`. |
 
 ### Example request
 
-```bash
-curl "https://api.trynawa.com/v1/analytics?platform=youtube&from=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&group_by=week" \
+<CodeGroup>
+
+```bash cURL
+curl "https://api.trynawa.com/v1/analytics?from=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&group_by=day" \
   -H "Authorization: Bearer nawa_test_sk_xxx"
 ```
 
+```typescript TypeScript
+import { Nawa } from '@nawalabs/sdk'
+
+const nawa = new Nawa({ apiKey: process.env.NAWA_API_KEY })
+
+const { data, error } = await nawa.analytics({
+  from: '2025-01-01T00:00:00Z',
+  to: '2025-01-31T23:59:59Z',
+  groupBy: 'endpoint'
+})
+
+console.log(data.analytics.total_requests)
+console.log(data.analytics.cache_hit_rate)
+```
+
+```python Python
+from nawa import Nawa
+
+nawa = Nawa(api_key="your_api_key")
+
+result = nawa.analytics(
+    from_date="2025-01-01T00:00:00Z",
+    to_date="2025-01-31T23:59:59Z",
+    group_by="endpoint"
+)
+
+print(result.data.analytics["total_requests"])
+print(result.data.analytics["cache_hit_rate"])
+```
+
+</CodeGroup>
+
 ## Response
 
 ### Success response (200)
 
+The breakdown key name is dynamic based on your `group_by` value: `by_endpoint`, `by_day`, or `by_provider`.
+
 ```json
 {
   "success": true,
   "result": {
-    "period": {
-      "from": "2025-01-01T00:00:00Z",
-      "to": "2025-01-31T23:59:59Z"
-    },
-    "total_comments": 4521,
-    "summary": {
-      "intent": {
-        "question": 1205,
-        "praise": 1890,
-        "complaint": 678,
-        "suggestion": 412,
-        "spam": 198,
-        "other": 138
+    "analytics": {
+      "total_requests": 4521,
+      "total_cost": 27.126,
+      "cache_hits": 1040,
+      "cache_hit_rate": 0.23,
+      "avg_latency_ms": 820,
+      "success_rate": 0.99,
+      "error_count": 45,
+      "endpoint_distribution": {
+        "/v1/classify": 3200,
+        "/v1/comments/reply": 800,
+        "/v1/detect": 521
       },
-      "sentiment": {
-        "positive": 2100,
-        "negative": 890,
-        "neutral": 1231,
-        "mixed": 300
+      "provider_distribution": {
+        "allam": 2800,
+        "claude": 1721
       },
-      "dialect": {
-        "gulf": 2015,
-        "egyptian": 1302,
-        "levantine": 789,
-        "msa": 415
-      },
-      "toxicity": {
-        "none": 3950,
-        "mild": 320,
-        "moderate": 180,
-        "severe": 71
+      "period": {
+        "from": "2025-01-01T00:00:00Z",
+        "to": "2025-01-31T23:59:59Z"
       }
     },
-    "trends": [
+    "by_endpoint": [
+      {
+        "endpoint": "/v1/classify",
+        "requests": 3200,
+        "cost": 19.2,
+        "avg_latency_ms": 750
+      },
       {
-        "period": "2025-01-06/2025-01-12",
-        "total": 1123,
-        "sentiment_score": 0.72,
-        "top_intent": "praise"
+        "endpoint": "/v1/comments/reply",
+        "requests": 800,
+        "cost": 6.4,
+        "avg_latency_ms": 1100
       }
     ]
   },
   "errors": [],
-  "request_id": "req_ana_abc123"
+  "request_id": "req_nw_ana_abc123"
 }
 ```
+
+### Analytics fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `analytics.total_requests` | integer | Total API requests in the period |
+| `analytics.total_cost` | number | Total cost in USD |
+| `analytics.cache_hits` | integer | Number of cache hit requests |
+| `analytics.cache_hit_rate` | number | Cache hit rate (0-1) |
+| `analytics.avg_latency_ms` | integer | Average response latency in milliseconds |
+| `analytics.success_rate` | number | Success rate (0-1) |
+| `analytics.error_count` | integer | Total error responses |
+| `analytics.endpoint_distribution` | object | Request count per endpoint |
+| `analytics.provider_distribution` | object | Request count per AI provider |
+| `analytics.period` | object | `from` and `to` date bounds applied |
+
+### Breakdown fields
+
+Each item in the `by_endpoint`, `by_day`, or `by_provider` array contains:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `endpoint` / `day` / `provider` | string | The grouping key |
+| `requests` | integer | Request count for this group |
+| `cost` | number | Cost in USD for this group |
+| `avg_latency_ms` | integer | Average latency for this group |