Guides

Usage reports

Pre-release v1, published 2026-09-14. This page commits to the shape of the API, not to a date. We will build exactly what is documented here. The shape can still change until 2026-10-14; after that, changes follow Versioning and stability.

The banner comes off one page at a time as each route goes live. While it is here, build against the contract and assume the route is not callable yet.

One endpoint reports activity for every robot on your account.

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
{
  "data": [
    {
      "robot_id": "rbt_8fK2mQ",
      "external_id": "shop_10422",
      "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
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total_count": 128, "has_more": true },
  "metadata": {
    "request_id": "req_8f2Kq9mR",
    "processed_at": "2026-10-01T09:15:22Z"
  }
}

by_role separates AI answers from human ones, which is what you need to show your own customers how much of their support the automation is carrying.

This reports robot activity, not your remaining balance. It answers “how much did this customer use?” rather than “how much is left on the account?”. Plan balance is out of scope for this API.

metadata.processed_at is the moment the figures are accurate as of. Usage is computed periodically, so a conversation from seconds ago may not be counted yet.

One robot

Pass robot_id to narrow the report to a single robot.

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

Paging

Page with limit and offset. pagination.total_count is the number of robots matching your query across every page, so you know how many calls to make before you start.

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

A customer whose volume comes mostly from story replies has a different product than one driven by comments, and a single total hides that.

curl "https://api-chat.parstechai.com/v1/usage?robot_id=rbt_8fK2mQ&from=2026-09-01T00:00:00Z&to=2026-09-30T23:59:59Z&breakdown=source" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx"
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"
  }
}

breakdown=source adds fields rather than replacing them. messages, conversations and channels_connected are still there, so one parser handles both shapes.

SourceMeaning
directA DM the customer started
commentTriggered by a comment on a post
story_replyThe customer replied to a story
story_mentionThe customer mentioned the account in their story
reelOriginated from a reel

The same source vocabulary appears on every message event, so you can attribute an event to its entry point without a second call.

Reconciling a gap

If a webhook delivery exhausted its retries, this API is how you find out. Compare the counts here against what you stored for the same window.