Skip to main content
GET
Get Usage
Subtotal Connector tool: get_usage Your plan usage for one window, the same figures as Settings · Usage in the dashboard: connections, purchases, events, MCP queries and API requests, each counted the way invoicing counts it and shown against your plan’s included amount and overage fee. An included of null means unlimited. The current window is the default. periods lists every window, newest first, including earlier plans’; pass one’s start as period_start to read it, with its plan_id if two plans’ windows share that start. Call it with your API key, or with a Subtotal Connector OAuth token that includes usage:read. A token without it receives 403 insufficient_scope. Partner app tokens don’t include it.

Authorizations

Authorization
string
header
required

Partner OAuth: send Authorization: Bearer <access_token>, an OAuth access token from Subtotal's authorization server with the scope this endpoint needs.

Query Parameters

period_start
string<date-time> | null

The start of a window from periods. Omit for the current window.

plan_id
string | null

The window's plan_id from periods. Needed only when two plans' windows share a start.

Maximum string length: 26

Response

Successful Response

plan_id
string
required
plan_name
string
required
current_plan
boolean
required

False when the window belongs to an earlier plan.

period_start
string<date-time>
required
period_end
string<date-time>
required
metrics
UsageMetric · object[]
required
periods
UsageWindow · object[]
required

Every usage window, newest first: the current plan's, then earlier plans'. Pass one's start as period_start to read it.