Skip to content

Sync API docs with current codebase #96

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 current codebase #96

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
161 changes: 119 additions & 42 deletions api-reference/analytics.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,63 @@
---
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, and cache performance."
api: "GET https://api.trynawa.com/v1/analytics"
---

Retrieve aggregated analytics across your classified comments. This endpoint is **free**.
Retrieve aggregated API usage analytics including request counts, costs, cache hit rates, latency, and endpoint/provider distribution. 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`. |
| `group_by` | string | No | Group the breakdown by: `endpoint` (default), `day`, `provider`. |

### 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=2026-04-01&to=2026-04-20&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({
from: '2026-04-01',
to: '2026-04-20',
group_by: '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="2026-04-01",
to_date="2026-04-20",
group_by="endpoint"
)

print(result.data.analytics.total_requests)
print(result.data.analytics.cache_hit_rate)
```

</CodeGroup>

## Response

### Success response (200)
Expand All @@ -34,49 +66,94 @@ 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": 1234,
"total_cost": 7.404,
"cache_hits": 500,
"cache_hit_rate": 0.41,
"avg_latency_ms": 230,
"success_rate": 0.98,
"error_count": 25,
"endpoint_distribution": {
"/v1/classify": 800,
"/v1/translate": 200,
"/v1/detect": 150,
"/v1/moderate": 84
},
"dialect": {
"gulf": 2015,
"egyptian": 1302,
"levantine": 789,
"msa": 415
"provider_distribution": {
"allam": 600,
"claude": 400,
"gemini": 234
},
"toxicity": {
"none": 3950,
"mild": 320,
"moderate": 180,
"severe": 71
"period": {
"from": "2026-04-01",
"to": "2026-04-20"
}
},
"trends": [
"by_endpoint": [
{
"endpoint": "/v1/classify",
"requests": 800,
"cost": 4.8,
"avg_latency_ms": 200
},
{
"period": "2025-01-06/2025-01-12",
"total": 1123,
"sentiment_score": 0.72,
"top_intent": "praise"
"endpoint": "/v1/translate",
"requests": 200,
"cost": 1.0,
"avg_latency_ms": 350
}
]
},
"errors": [],
"request_id": "req_ana_abc123"
"request_id": "req_nw_ana_abc123"
}
```

### 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 requests served from cache |
| `analytics.cache_hit_rate` | number | Ratio of cache hits to total requests (0-1) |
| `analytics.avg_latency_ms` | integer | Average response latency in milliseconds |
| `analytics.success_rate` | number | Ratio of successful (2xx) responses (0-1) |
| `analytics.error_count` | integer | Number of error (4xx/5xx) responses |
| `analytics.endpoint_distribution` | object | Request counts per endpoint |
| `analytics.provider_distribution` | object | Request counts per AI provider |
| `analytics.period` | object | Applied date filters (`from` and `to`, null if unset) |
| `by_endpoint` | array | Breakdown grouped by the `group_by` parameter. Each entry has the group key, `requests`, `cost`, and `avg_latency_ms`. |

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

### Grouping examples

<AccordionGroup>
<Accordion title="Group by day">
```bash
curl "https://api.trynawa.com/v1/analytics?group_by=day&from=2026-04-15" \
-H "Authorization: Bearer nawa_test_sk_xxx"
```

The response `by_day` array contains entries like:
```json
{"day": "2026-04-15", "requests": 120, "cost": 0.72, "avg_latency_ms": 210}
```
</Accordion>

<Accordion title="Group by provider">
```bash
curl "https://api.trynawa.com/v1/analytics?group_by=provider" \
-H "Authorization: Bearer nawa_test_sk_xxx"
```

The response `by_provider` array contains entries like:
```json
{"provider": "allam", "requests": 600, "cost": 3.0, "avg_latency_ms": 180}
```
</Accordion>
</AccordionGroup>
92 changes: 66 additions & 26 deletions api-reference/comments-list.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,61 +1,65 @@
---
title: "List Comments"
title: "List comments"
sidebarTitle: "GET /v1/comments"
description: "Retrieve and filter classified comments with pagination."
description: "Retrieve and filter classified comments with offset-based 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. Returns comments stored from prior `/v1/classify` calls. 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)
for (const comment of data.comments) {
console.log(comment.text, comment.dialect)
}
```

```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)
for comment in result.data.comments:
print(comment.text, comment.dialect)
```

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

### Result fields

| Field | Type | Description |
|-------|------|-------------|
| `comments` | array | Array of classified comment objects |
| `comments[].id` | string | Database record UUID |
| `comments[].request_id` | string | Original request ID from the classify call |
| `comments[].text` | string | Comment text |
| `comments[].platform` | string | Source platform |
| `comments[].intent` | string | Detected intent label |
| `comments[].sentiment` | string | Detected sentiment |
| `comments[].dialect` | string | Detected Arabic dialect |
| `comments[].created_at` | string | ISO 8601 timestamp |
| `pagination.total` | integer | Total number of matching comments |
| `pagination.limit` | integer | Current page size |
| `pagination.offset` | integer | Current offset |
| `pagination.has_more` | boolean | Whether more results exist beyond the current page |

### Pagination

Use `offset` and `limit` to paginate through results. Increment `offset` by `limit` to fetch the next page:

```bash
# Page 1
curl "https://api.trynawa.com/v1/comments?limit=25&offset=0" \
-H "Authorization: Bearer nawa_test_sk_xxx"

# Page 2
curl "https://api.trynawa.com/v1/comments?limit=25&offset=25" \
-H "Authorization: Bearer nawa_test_sk_xxx"
```

<Note>
Comment history storage is a recent feature. If no classifications have been stored yet, the endpoint returns an empty `comments` array with a helpful `message` field.
</Note>
Loading