Skip to content

Sync API docs with current codebase #94

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 #94

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
146 changes: 102 additions & 44 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 analytics on API usage, cache performance, and provider distribution."
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 including request counts, costs, cache hit rates, latency, and 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`. |
| `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" \
-H "Authorization: Bearer nawa_test_sk_xxx"
<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_live_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',
})
```

```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",
)
```

</CodeGroup>

## Response

### Success response (200)
Expand All @@ -34,49 +60,81 @@ 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
"analytics": {
"total_requests": 12450,
"total_cost": 68.70,
"cache_hits": 2231,
"cache_hit_rate": 0.18,
"avg_latency_ms": 820,
"success_rate": 0.98,
"error_count": 249,
"endpoint_distribution": {
"/v1/classify": 8500,
"/v1/translate": 1200,
"/v1/detect": 950,
"/v1/moderate": 800,
"/v1/comments/reply": 1000
},
"sentiment": {
"positive": 2100,
"negative": 890,
"neutral": 1231,
"mixed": 300
"provider_distribution": {
"claude": 9200,
"allam": 3250
},
"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": 8500,
"cost": 51.00,
"avg_latency_ms": 780
},
{
"period": "2025-01-06/2025-01-12",
"total": 1123,
"sentiment_score": 0.72,
"top_intent": "praise"
"endpoint": "/v1/translate",
"requests": 1200,
"cost": 6.00,
"avg_latency_ms": 1100
}
]
},
"errors": [],
"request_id": "req_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 cache hits |
| `analytics.cache_hit_rate` | number | Ratio of cache hits to total requests (0 to 1) |
| `analytics.avg_latency_ms` | integer | Average response latency in milliseconds |
| `analytics.success_rate` | number | Ratio of 2xx responses to total requests (0 to 1) |
| `analytics.error_count` | integer | Number of 4xx/5xx responses |
| `analytics.endpoint_distribution` | object | Request count per endpoint |
| `analytics.provider_distribution` | object | Request count per AI provider |
| `analytics.period` | object | The `from` and `to` dates applied (null if not specified) |

The `by_endpoint`, `by_day`, or `by_provider` array (matching your `group_by` choice) contains objects with:

| Field | Type | Description |
|-------|------|-------------|
| `endpoint` / `day` / `provider` | string | The group key |
| `requests` | integer | Request count for this group |
| `cost` | number | Total cost in USD for this group |
| `avg_latency_ms` | integer | Average latency for this group |

### 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 |

See [Errors](/errors) for the full envelope shape and all error codes.
84 changes: 57 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 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 to 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" \
-H "Authorization: Bearer nawa_test_sk_xxx"
curl "https://api.trynawa.com/v1/comments?platform=youtube&intent=question&limit=10&offset=0" \
-H "Authorization: Bearer nawa_live_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 @@ -71,23 +68,56 @@ for comment in nawa.comments.list(platform="youtube"):
"comments": [
{
"id": "cmt_abc123",
"request_id": "req_nw_9cfb228162d6",
"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 | Comment ID |
| `comments[].request_id` | string | Original classification request ID |
| `comments[].text` | string | Comment text |
| `comments[].platform` | string | Source platform |
| `comments[].intent` | string | Classified intent |
| `comments[].sentiment` | string | Classified 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 exist |

<Note>
Comment history storage may not be enabled on all accounts. If the underlying table does not exist yet, the endpoint returns an empty array with a `message` field explaining the status.
</Note>

### Error responses

| Status | Type | When |
|--------|------|------|
| 400 | `invalid_request_error` | Invalid `platform`, `intent`, `sentiment`, or `dialect` value |
| 401 | `authentication_error` | Invalid or missing API key |
| 429 | `rate_limit_error` | Rate limit exceeded |
| 500 | `api_error` | Internal error |

See [Errors](/errors) for the full envelope shape and all error codes.
Loading