SMAO API Documentation
Public APIStatistics

Usage breakdown for a week + assistant filter

GET
/statistics/usage

Returns the monthly + weekly + last-24h breakdown for the selected week/year window. assistant_id=all aggregates across every assistant; passing a concrete 24-hex ID filters to that assistant's calls only. Supplying an ID that does not belong to the caller's organization returns 404.

All duration fields are integer seconds (billable, with 60s minimum per call), not minutes. hourly_call_counts_last_24h always reflects the 24h window ending at request time — it ignores the week/year filter.

Authorization

bearerAuth
AuthorizationBearer <token>

API key in the Authorization: Bearer <key> header. Keys are created in the SMAO dashboard (Settings → API Keys).

In: header

Query Parameters

week*integer

ISO week number (1–53).

Range1 <= value <= 53
year*integer
Range2020 <= value <= 2100
assistant_id*|

Either the sentinel all or a 24-hex assistant id.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/statistics/usage?week=1&year=2020&assistant_id=all"
{  "data": {    "period": {      "week": 0,      "year": 0    },    "assistant_id": "all",    "monthly": {      "property1": {        "call_count": 0,        "overall_call_seconds": 0,        "average_calls_per_day": 0,        "daily_call_counts": [          {            "date": "string",            "count": 0          }        ]      },      "property2": {        "call_count": 0,        "overall_call_seconds": 0,        "average_calls_per_day": 0,        "daily_call_counts": [          {            "date": "string",            "count": 0          }        ]      }    },    "weekly_call_counts": [],    "weekly_call_seconds": [],    "hourly_call_counts_last_24h": [      0,      0,      0,      0,      0,      0,      0,      0,      0,      0,      0,      0,      0,      0,      0,      0,      0,      0,      0,      0,      0,      0,      0,      0    ]  }}

List available statistics filters GET

Returns the filter values that populate statistics dashboards: every (week, year) pair that has at least one completed call in the organization, plus every assistant in the organization. The `all` assistant sentinel is **not** returned — clients can always pass `assistant_id=all` to the `/usage` endpoint regardless of this list.

Per-assistant usage for a week GET

Returns one breakdown row per assistant that had at least one completed call in the selected week. Includes assistants that have since been deleted — their calls still count and the row carries `is_deleted: true`. All duration fields are integer seconds (billable, with 60s minimum).