Skip to content

Sync API docs with codebase: fix 7 endpoints, OpenAPI spec, billing #84

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Sync API docs with codebase: fix 7 endpoints, OpenAPI spec, billing #84

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
137 changes: 94 additions & 43 deletions api-reference/analytics.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,57 @@
---
title: "Analytics"
sidebarTitle: "GET /v1/analytics"
description: "Aggregated analytics on comment trends, sentiment shifts, and engagement patterns."
description: "Aggregated API analytics including request counts, costs, and cache hit rates."
api: "GET https://api.trynawa.com/v1/analytics"
---

Retrieve aggregated analytics across your classified comments. This endpoint is **free**.
Retrieve aggregated analytics across your API usage, including request counts, costs, cache performance, and error rates. 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). |
| `to` | string | No | End date (ISO 8601). |
| `group_by` | string | No | Group results 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=endpoint" \
-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.get({
from: '2025-01-01T00:00:00Z',
to: '2025-01-31T23:59:59Z',
groupBy: 'endpoint'
})
```

```python Python
from nawa import Nawa

nawa = Nawa(api_key="your_api_key")

result = nawa.analytics.get(
from_date="2025-01-01T00:00:00Z",
to_date="2025-01-31T23:59:59Z",
group_by="endpoint"
)
```

</CodeGroup>

## Response

### Success response (200)
Expand All @@ -34,49 +60,74 @@ curl "https://api.trynawa.com/v1/analytics?platform=youtube&from=2025-01-01T00:0
{
"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
},
"sentiment": {
"positive": 2100,
"negative": 890,
"neutral": 1231,
"mixed": 300
"analytics": {
"total_requests": 12450,
"total_cost": 68.70,
"cache_hits": 2831,
"cache_hit_rate": 0.23,
"avg_latency_ms": 820,
"success_rate": 0.98,
"error_count": 249,
"endpoint_distribution": {
"/v1/classify": 8500,
"/v1/translate": 1200,
"/v1/comments/reply": 1750,
"/v1/detect": 1000
},
"dialect": {
"gulf": 2015,
"egyptian": 1302,
"levantine": 789,
"msa": 415
"provider_distribution": {
"allam": 9200,
"claude": 3250
},
"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": [
{
"period": "2025-01-06/2025-01-12",
"total": 1123,
"sentiment_score": 0.72,
"top_intent": "praise"
"endpoint": "/v1/classify",
"requests": 8500,
"cost": 51.00,
"avg_latency_ms": 780
},
{
"endpoint": "/v1/comments/reply",
"requests": 1750,
"cost": 14.00,
"avg_latency_ms": 1200
}
]
},
"errors": [],
"request_id": "req_ana_abc123"
}
```

<Note>
The breakdown key changes based on `group_by`: `by_endpoint`, `by_day`, or `by_provider`.
</Note>

### Result 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 hits |
| `analytics.cache_hit_rate` | number | Cache hit ratio (0-1) |
| `analytics.avg_latency_ms` | integer | Average response latency in milliseconds |
| `analytics.success_rate` | number | Ratio of successful (2xx) requests (0-1) |
| `analytics.error_count` | integer | Number of error (4xx/5xx) responses |
| `analytics.endpoint_distribution` | object | Request count by endpoint |
| `analytics.provider_distribution` | object | Request count by AI provider |
| `analytics.period` | object | The date range queried |
| `by_endpoint` | array | Breakdown by the selected `group_by` dimension |

### Error responses

| Status | Type | When |
|--------|------|------|
| 400 | `invalid_request_error` | Invalid `group_by` value |
| 401 | `authentication_error` | Invalid or missing API key |
| 429 | `rate_limit_error` | Rate limit exceeded |
| 500 | `api_error` | Internal error |
78 changes: 51 additions & 27 deletions api-reference/comments-list.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,61 +1,58 @@
---
title: "List Comments"
title: "List comments"
sidebarTitle: "GET /v1/comments"
description: "Retrieve and filter classified comments with pagination."
api: "GET https://api.trynawa.com/v1/comments"
---

Retrieve classified comments with filtering and pagination. This endpoint is **free**.
Retrieve previously classified comments with filtering and offset-based pagination. 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: `youtube`, `instagram`, `twitter`, `facebook` |
| `intent` | string | No | Filter by intent: `question`, `complaint`, `praise`, `suggestion`, `spam`, `other` |
| `sentiment` | string | No | Filter by sentiment: `positive`, `negative`, `neutral`, `mixed` |
| `dialect` | string | No | Filter by dialect: `gulf`, `egyptian`, `levantine`, `msa` |
| `toxicity` | string | No | Filter by toxicity: `none`, `mild`, `moderate`, `severe` |
| `from` | string | No | Start date (ISO 8601): `2025-01-01T00:00:00Z` |
| `to` | string | No | End date (ISO 8601): `2025-01-31T23:59:59Z` |
| `limit` | integer | No | Results per page (1–100). Default: 25. |
| `cursor` | string | No | Pagination cursor from previous response. |
| `limit` | integer | No | Results per page (1-100). Default: 25. |
| `offset` | integer | No | Number of results to skip. Default: 0. |

### Example request

<CodeGroup>

```bash cURL
curl "https://api.trynawa.com/v1/comments?platform=youtube&intent=question&limit=10" \
curl "https://api.trynawa.com/v1/comments?platform=youtube&intent=question&limit=10&offset=0" \
-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.comments.list({
platform: 'youtube',
intent: 'question',
limit: 10
limit: 10,
offset: 0
})

// Auto-pagination
for await (const comment of nawa.comments.list({ platform: 'youtube' })) {
console.log(comment.text)
}
```

```python Python
from nawa import Nawa

nawa = Nawa(api_key="your_api_key")

result = nawa.comments.list(
platform="youtube",
intent="question",
limit=10
limit=10,
offset=0
)

# Auto-pagination
for comment in nawa.comments.list(platform="youtube"):
print(comment.text)
```

</CodeGroup>
Expand All @@ -70,24 +67,51 @@ for comment in nawa.comments.list(platform="youtube"):
"result": {
"comments": [
{
"id": "cmt_abc123",
"id": "cls_abc123",
"request_id": "req_nw_a1b2c3",
"text": "متى الجزء الثاني؟",
"platform": "youtube",
"intent": "question",
"sentiment": "neutral",
"dialect": "gulf",
"toxicity": "none",
"created_at": "2025-01-15T10:30:00Z",
"channel_id": "ch_123"
"created_at": "2025-01-15T10:30:00Z"
}
],
"pagination": {
"has_more": true,
"next_cursor": "cur_def456",
"total_count": 1523
"total": 1523,
"limit": 10,
"offset": 0,
"has_more": true
}
},
"errors": [],
"request_id": "req_lst_abc123"
}
```

### Result fields

| Field | Type | Description |
|-------|------|-------------|
| `comments` | array | Array of classified comment objects |
| `comments[].id` | string | Classification record ID |
| `comments[].request_id` | string | Original API request ID |
| `comments[].text` | string | The classified text |
| `comments[].platform` | string | Source platform |
| `comments[].intent` | string | Detected intent |
| `comments[].sentiment` | string | Detected sentiment |
| `comments[].dialect` | string | Detected dialect |
| `comments[].created_at` | string | ISO 8601 timestamp |
| `pagination.total` | integer | Total matching comments |
| `pagination.limit` | integer | Results per page |
| `pagination.offset` | integer | Current offset |
| `pagination.has_more` | boolean | Whether more results are available |

### Error responses

| Status | Type | When |
|--------|------|------|
| 400 | `invalid_request_error` | Invalid filter values |
| 401 | `authentication_error` | Invalid or missing API key |
| 429 | `rate_limit_error` | Rate limit exceeded |
| 500 | `api_error` | Internal error |
Loading