> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage Summary

> Aggregated spend and volume for a billing period, across your whole portfolio or one child.

Returns a per-account rollup of billed spend, refunds, and message volume for a period, plus portfolio totals. Called on a **parent** key, it covers the parent and all its children by default; scope to one child with `childAccountId`.

## Query Parameters

<ParamField query="period" type="string" default="current month">
  The billing month as `YYYY-MM`.
</ParamField>

<ParamField query="childAccountId" type="integer">
  Restrict the summary to one owned child. Omit to include the caller plus all children.
</ParamField>

## Response Fields

<ResponseField name="period" type="string">The `YYYY-MM` period reported.</ResponseField>
<ResponseField name="generated_at" type="string">When the summary was computed (ISO-8601, UTC).</ResponseField>

<ResponseField name="accounts" type="array">
  One entry per account in scope.

  <Expandable title="account entry">
    <ResponseField name="account_id" type="integer">The account ID.</ResponseField>
    <ResponseField name="name" type="string">Account name.</ResponseField>
    <ResponseField name="external_ids" type="object">External IDs (e.g. `location_id`).</ResponseField>
    <ResponseField name="currency" type="string">Currency (e.g. `usd`).</ResponseField>
    <ResponseField name="billed_total" type="number">Sum of succeeded + refunded charge amounts.</ResponseField>
    <ResponseField name="refunds_total" type="number">Sum of refunded amounts.</ResponseField>
    <ResponseField name="net_total" type="number">`billed_total − refunds_total`.</ResponseField>
    <ResponseField name="bypassed_total" type="number">Amount that would have been billed but was comped/bypassed.</ResponseField>
    <ResponseField name="segments" type="integer">Billed segment count.</ResponseField>
    <ResponseField name="messages" type="integer">Billed message count.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="totals" type="object">Portfolio totals across all accounts in scope (same fields plus `currency`).</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -G https://api.tracklysms.com/api/v2/usage/summary \
    -H "X-Api-Key: trk_your_parent_key" \
    --data-urlencode "period=2026-07"
  ```
</RequestExample>

<ResponseExample>
  ```json Success (200) theme={null}
  {
    "period": "2026-07",
    "generated_at": "2026-07-26T16:00:00Z",
    "accounts": [
      {
        "account_id": 1042,
        "name": "Acme West",
        "external_ids": { "location_id": "loc_west" },
        "currency": "usd",
        "billed_total": 812.44,
        "refunds_total": 0.0,
        "net_total": 812.44,
        "bypassed_total": 0.0,
        "segments": 180542,
        "messages": 175003
      }
    ],
    "totals": {
      "billed_total": 812.44,
      "refunds_total": 0.0,
      "net_total": 812.44,
      "bypassed_total": 0.0,
      "segments": 180542,
      "messages": 175003,
      "currency": "usd"
    }
  }
  ```
</ResponseExample>

## Error Codes

| HTTP Status | Error Code        | Description                                 |
| ----------- | ----------------- | ------------------------------------------- |
| 400         | `invalid_period`  | `period` is not a valid `YYYY-MM`.          |
| 400         | `invalid_child`   | `childAccountId` is malformed.              |
| 404         | `child_not_found` | The `childAccountId` is not an owned child. |

## Next Steps

<CardGroup cols={2}>
  <Card title="Billing records" icon="receipt" href="/api-reference/v2/usage/billing-records">
    The individual charges and refunds behind these totals.
  </Card>

  <Card title="Statements" icon="file-lines" href="/api-reference/v2/usage/billing-statements">
    A footed statement for one account and period.
  </Card>
</CardGroup>