> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-parschat.parstechai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-parschat.parstechai.com/_mcp/server.

# گزارش‌های مصرف

> پیام‌ها، واحدها و گفتگوهای هر ربات در هر بازه زمانی، با صفحه‌بندی مبتنی بر offset.

> **Note**
>
> **این اندپوینت فعال است.** همه موارد این صفحه قابل فراخوانی‌اند، به‌جز
> [تفکیک اینستاگرام بر اساس نقطه ورود](#instagram-breakdown-by-entry-point) که هنوز
> پیش‌انتشار است و ابتدای آن مشخص شده است.

یک اندپوینت، فعالیت همه ربات‌های حساب شما را گزارش می‌کند.

```bash
curl "https://api-chat.parstechai.com/v1/usage?from=2026-09-01T00:00:00Z&to=2026-09-30T23:59:59Z" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx"
```

**`Response`**

```json Response
{
  "window": { "from": "2026-09-01T00:00:00Z", "to": "2026-09-30T23:59:59Z" },
  "data": [
    {
      "robot_id": "a3f9c21b4e7d40a8",
      "external_id": "shop_10422",
      "name": "Rose Flower Shop",
      "messages": {
        "total": 1840,
        "units": 1840,
        "by_role": { "client": 900, "ai": 820, "operator": 120 }
      },
      "conversations": { "total": 312 },
      "channels_connected": 1
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total_count": 128, "has_more": true },
  "metadata": {
    "processed_at": "2026-10-01T09:15:22Z",
    "cache_hit": false
  }
}
```

`by_role` پاسخ‌های هوش مصنوعی را از پاسخ‌های انسانی جدا می‌کند؛ همان چیزی که برای نشان‌دادن سهم
خودکارسازی از پشتیبانی به مشتریان خودتان لازم دارید.

> **Warning**
>
> **`messages.total` و `messages.units` یک عدد نیستند.** رباتی که از مدل با دقت بالاتر استفاده
> می‌کند، به ازای هر پیام **دو** واحد مصرف می‌کند؛ پس مشتری‌ای که روی این مدل ۱٬۰۰۰ پیام فرستاده،
> `total: 1000` و `units: 2000` نشان می‌دهد.
>
> تطبیق صورتحساب را با `units` انجام دهید. `total` را به‌عنوان تعداد پیام به مشتری نشان دهید.

> **Info**
>
> `external_id` شناسه **شما** برای ربات است. تا زمانی که ساخت ربات از طریق API منتشر نشود، مقدار آن
> `null` است؛ پس امروز همه ربات‌ها این‌جا `null` برمی‌گردانند. تا آن زمان تطبیق را بر اساس `robot_id`
> انجام دهید.

بازه پیش‌فرض ۳۰ روز گذشته است و نمی‌تواند بیش از یک سال باشد. درخواست بازه‌ای بزرگ‌تر، `from` بعد
از `to`، یا `limit` بیشتر از 100، خطای `400` برمی‌گرداند.

> **Info**
>
> این گزارش فعالیت ربات‌ها را نشان می‌دهد، نه موجودی باقی‌مانده شما را. به این پرسش پاسخ می‌دهد که
> «این مشتری چقدر مصرف کرد؟»، نه «چقدر از حساب باقی مانده است؟». موجودی بسته خارج از محدوده این API
> است.
>
> `metadata.processed_at` لحظه‌ای است که ارقام تا آن زمان دقیق‌اند. مصرف به‌صورت دوره‌ای محاسبه
> می‌شود، پس ممکن است گفتگویی که چند ثانیه پیش انجام شده هنوز شمرده نشده باشد.

## یک ربات

برای محدودکردن گزارش به یک ربات، `robot_id` را بفرستید.

```bash
curl "https://api-chat.parstechai.com/v1/usage?robot_id=a3f9c21b4e7d40a8&from=2026-09-01T00:00:00Z&to=2026-09-30T23:59:59Z" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx"
```

## صفحه‌بندی

با `limit` و `offset` صفحه‌بندی کنید. `pagination.total_count` تعداد ربات‌های منطبق با درخواست شما
در همه صفحه‌هاست؛ پس پیش از شروع می‌دانید چند فراخوانی لازم است.

```bash
curl "https://api-chat.parstechai.com/v1/usage?from=2026-09-01T00:00:00Z&to=2026-09-30T23:59:59Z&limit=50&offset=50" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx"
```

**`Python`**

```python Python
import math, requests

params = {"from": FROM, "to": TO, "limit": 50, "offset": 0}
first = requests.get(URL, headers=HEADERS, params=params, timeout=30).json()

pages = math.ceil(first["pagination"]["total_count"] / first["pagination"]["limit"])
robots = list(first["data"])

for page in range(1, pages):
    params["offset"] = page * params["limit"]
    robots += requests.get(URL, headers=HEADERS, params=params, timeout=30).json()["data"]
```

## تفکیک اینستاگرام بر اساس نقطه ورود \[#instagram-breakdown-by-entry-point]

> **Warning**
>
> **پیش‌انتشار؛ هنوز قابل فراخوانی نیست.** این بخش شکل API را تعهد می‌کند، نه تاریخ آن را. ارسال
> `breakdown=source` در حال حاضر همان پاسخ استاندارد بالا را بدون فیلدهای اضافه برمی‌گرداند. بقیه
> موارد این صفحه فعال‌اند.

مشتری‌ای که بیشتر حجمش از پاسخ به استوری می‌آید، محصولی متفاوت از مشتری‌ای دارد که کامنت‌ها آن را
پیش می‌برند؛ و یک `total` واحد این تفاوت را پنهان می‌کند.

```bash
curl "https://api-chat.parstechai.com/v1/usage?robot_id=a3f9c21b4e7d40a8&from=2026-09-01T00:00:00Z&to=2026-09-30T23:59:59Z&breakdown=source" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx"
```

**`Response`**

```json Response
{
  "data": [
    {
      "robot_id": "rbt_8fK2mQ",
      "external_id": "shop_10422",
      "channel": "instagram",
      "window": { "from": "2026-09-01T00:00:00Z", "to": "2026-09-30T23:59:59Z" },
      "messages": {
        "total": 1840,
        "by_role": { "client": 900, "ai": 820, "operator": 120 }
      },
      "conversations": { "total": 312 },
      "channels_connected": 1,
      "by_source": {
        "direct":        { "conversations": 180, "messages": 1120 },
        "comment":       { "conversations":  84, "messages":  310 },
        "story_reply":   { "conversations":  36, "messages":  290 },
        "story_mention": { "conversations":  12, "messages":  120 }
      },
      "totals": { "conversations": 312, "messages": 1840 }
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total_count": 1, "has_more": false },
  "metadata": {
    "request_id": "req_8f2Kq9mR",
    "processed_at": "2026-10-01T09:15:22Z"
  }
}
```

> **Info**
>
> `breakdown=source` فیلدهایی **اضافه** می‌کند و چیزی را جایگزین نمی‌کند. `messages`،
> `conversations` و `channels_connected` همچنان وجود دارند؛ پس یک تجزیه‌گر هر دو شکل را پوشش می‌دهد.

| منبع            | معنی                                       |
| --------------- | ------------------------------------------ |
| `direct`        | دایرکتی که مشتری شروع کرده است             |
| `comment`       | با یک کامنت زیر پست ایجاد شده است          |
| `story_reply`   | مشتری به یک استوری پاسخ داده است           |
| `story_mention` | مشتری در استوری خودش حساب را منشن کرده است |
| `reel`          | از یک ریلز آغاز شده است                    |

همین واژگان `source` در هر رویداد `message` هم می‌آید؛ پس می‌توانید بدون فراخوانی دوم، هر رویداد را
به نقطه ورودش نسبت دهید.

## پیدا کردن کسری‌ها

اگر تحویل یک وب‌هوک همه [تلاش‌های دوباره](/documentation/guides/webhook-events#retries) خود را مصرف
کرده باشد، از طریق همین API متوجه می‌شوید. شمارش‌های این‌جا را با آنچه برای همان بازه ذخیره کرده‌اید
مقایسه کنید.