Usage Statistics
| Tool | REST Endpoint | Annotations |
|---|---|---|
get_usage_period | GET /v1/usage/period | read, idempotent |
get_usage_summary | GET /v1/usage/summary | read, idempotent |
get_usage_messages | GET /v1/usage/messages | read, idempotent |
get_usage_conversations | GET /v1/usage/conversations | read, idempotent |
get_usage_actors | GET /v1/usage/actors | read, idempotent |
get_usage_period
Returns the active billing period for the workspace: billing type, plan, and included credits.
| Field | Type | Required | Description |
|---|---|---|---|
workspace | string | no | Workspace ID. If omitted, returns all workspaces accessible by the API key. |
get_usage_summary
Returns the main monitoring summary: messages used, included credits, conversations, and autonomy rate.
| Field | Type | Required | Description |
|---|---|---|---|
workspace | string | no | Workspace ID. If omitted, returns all accessible workspaces. |
startDate | string | no | ISO 8601 start date with offset. If omitted, uses the start of the billing period. |
endDate | string | no | ISO 8601 end date with offset. If omitted, uses the end of the billing period. |
get_usage_messages
Returns daily message series and totals. Distinguishes total volume, charged messages, and failed/non-billable messages.
| Field | Type | Required | Description |
|---|---|---|---|
workspace | string | no | Workspace ID. If omitted, returns all accessible workspaces. |
startDate | string | no | ISO 8601 start date with offset. |
endDate | string | no | ISO 8601 end date with offset. |
groupBy | enum | no | type (default), channel, templateCategory, campaign, or status. |
mode | enum | no | fast (default, daily aggregates) or full (transactions, maximum 92 days). Enterprise always uses fast. |
universe | enum | no | all (default, includes failed/non-billable messages) or billable (charged messages only). |
The response includes totalMessages, billableMessages, nonBillableMessages, and failedMessages. Each totalsByGroup row includes nonBillableMessages and, in fast mode, changePct vs the previous period.
get_usage_conversations
Returns conversation and autonomy metrics, with breakdowns by platform, agent, channel, or tag.
| Field | Type | Required | Description |
|---|---|---|---|
workspace | string | no | Workspace ID. If omitted, returns all accessible workspaces. |
startDate | string | no | ISO 8601 start date with offset. |
endDate | string | no | ISO 8601 end date with offset. |
breakdown | enum | no | platform (default), agent, channel, or tag. |
get_usage_actors
Returns message consumption by actor: automatic agents, workspace users, contacts, and other buckets captured by Platica.
| Field | Type | Required | Description |
|---|---|---|---|
workspace | string | no | Workspace ID. If omitted, returns all accessible workspaces. |
startDate | string | no | ISO 8601 start date with offset. |
endDate | string | no | ISO 8601 end date with offset. |