Message Usage

Returns daily series and message totals. The response distinguishes total volume, billable messages, and failed/non-billable messages.

GET https://api.platica.mx/v1/usage/messages

Query parameters

Parameter	Type	Description	Required
`workspace`	string	Filters the response to one workspace. If omitted, returns all accessible workspaces	—
`startDate`	string	ISO 8601 start date with offset. Defaults to the billing-period start	—
`endDate`	string	ISO 8601 end date with offset. Defaults to the billing-period end	—
`groupBy`	enum	`type` (default), `channel`, `templateCategory`, `campaign`, or `status`	—
`mode`	enum	`fast` (default) uses daily aggregates; `full` reads transactions for detailed costs	—
`universe`	enum	`all` (default) includes failed/non-billable messages; `billable` shows only charged messages	—

Example: billable messages only

curl "https://api.platica.mx/v1/usage/messages?workspace=g6yCA16pkWl5eXo7KszB&groupBy=status&universe=billable" \
  -H "Authorization: Bearer $PLATICA_API_KEY"

Response

{
  "workspaces": [
    {
      "id": "g6yCA16pkWl5eXo7KszB",
      "name": "My company",
      "billingPeriod": {
        "startDate": "2026-06-01T06:00:00.000Z",
        "endDate": "2026-07-01T05:59:59.999Z"
      },
      "dataSince": "2026-05-21T06:00:00.000Z",
      "universe": "all",
      "usage": {
        "planName": "Growth",
        "credits": 6500,
        "mode": "fast",
        "groupBy": "type",
        "range": {
          "startDate": "2026-06-01T06:00:00.000Z",
          "endDate": "2026-07-01T05:59:59.999Z"
        },
        "freshness": {
          "source": "daily_aggregations",
          "lastUpdated": "2026-06-29T18:31:10.000Z",
          "expectedLagSeconds": 30
        },
        "series": [
          { "date": "2026-06-29T12:00:00.000Z", "group": "Servicio", "value": 180 },
          { "date": "2026-06-29T12:00:00.000Z", "group": "Campaña", "value": 40 }
        ],
        "totalsByGroup": [
          { "group": "Servicio", "messages": 950, "nonBillableMessages": 0, "creditsUsed": 950, "includedValueCentavos": 0, "overageCentavos": 0, "changePct": -11.2 },
          { "group": "Campaña", "messages": 250, "nonBillableMessages": 12, "creditsUsed": 358, "includedValueCentavos": 0, "overageCentavos": 0, "changePct": 0 }
        ],
        "summary": {
          "totalMessages": 1200,
          "billableMessages": 1188,
          "nonBillableMessages": 12,
          "failedMessages": 12,
          "serviceCount": 950,
          "campaignCount": 250,
          "creditsUsed": 1308,
          "credits": 6500,
          "totalChangePct": -8.8,
          "serviceChangePct": -11.2,
          "campaignChangePct": 0
        }
      }
    }
  ],
  "workspacesCount": 1
}

Main fields

Field	Description
`universe`	Requested universe: `all` or `billable`
`usage.mode`	Effective mode. Enterprise always returns `fast`
`usage.groupBy`	Applied grouping dimension
`usage.range`	Effective evaluated range
`usage.series`	Daily series for the selected universe
`usage.totalsByGroup[].messages`	Group messages within the selected universe
`usage.totalsByGroup[].nonBillableMessages`	Group messages that are not charged
`usage.totalsByGroup[].changePct`	Change vs the immediately preceding equal-length period. May be `null` in `full` mode
`usage.summary.totalMessages`	Total volume, including failed/non-billable messages
`usage.summary.billableMessages`	Messages that are charged
`usage.summary.nonBillableMessages`	Messages that are not charged
`usage.summary.failedMessages`	Failed messages; they do not consume balance
`usage.summary.creditsUsed`	Credits consumed (omitted for enterprise)
`usage.freshness`	Source, latest update, and expected lag

Modes

Mode	Recommended use
`fast`	Dashboards and monitoring. Includes per-group change and normally lags by seconds
`full`	Exact transaction-based cost reconciliation. Maximum 92 days; per-group `changePct` may be `null`

Nota

Enterprise always uses aggregates (mode: "fast"), even when mode=full is requested. creditsUsed and cost fields are omitted because rates are contract-specific, while nonBillableMessages and per-group changePct remain available.

Previous Usage Summary Next Conversation Usage