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

# Usage & billing

> Track API usage and billing for your partner account

Monitor your API usage by billing period. Usage records track every billable operation and are summarized monthly.

## Billing periods

Billing periods use the `YYYY-MM` format (e.g., `2026-03`). If no period is specified, the current month is used.

## Usage summary

Get an aggregated summary of usage for a billing period:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.contro.me/v1/partner/usage/summary?period=2026-03" \
    -H "x-contro-api-key: $CONTRO_API_KEY"
  ```

  ```typescript SDK (Node) theme={null}
  const summary = await contro.usage.getSummary({ period: "2026-03" });

  for (const item of summary.items) {
    console.log(`${item.type}: ${item.count} operations, $${item.total}`);
  }
  ```

  ```python SDK (Python) theme={null}
  summary = contro.usage.get_summary(period="2026-03")

  for item in summary.items:
      print(f"{item.type}: {item.count} operations, ${item.total}")
  ```

  ```typescript TypeScript (fetch) theme={null}
  const summary = await fetch(
    `${BASE_URL}/partner/usage/summary?period=2026-03`,
    { headers }
  ).then((r) => r.json());

  for (const item of summary.items) {
    console.log(`${item.type}: ${item.count} operations, $${item.total}`);
  }
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "period": "2026-03",
  "items": [
    { "type": "card_issuance", "total": 150.00, "count": 30 },
    { "type": "transaction", "total": 45.50, "count": 910 },
    { "type": "kyc", "total": 75.00, "count": 25 },
    { "type": "monthly_fee", "total": 50.00, "count": 1 }
  ]
}
```

### Summary item fields

| Field | Type | Description |
| - | - | - |
| `type` | string | Usage type. One of `card_issuance`, `transaction`, `monthly_fee`, `api_call`, `kyc` |
| `total` | number | Total cost for this type in USD. Example: `150.00` |
| `count` | number | Number of operations in this period. Example: `30` |

## Detailed usage records

List individual usage records with optional filtering:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.contro.me/v1/partner/usage/records?period=2026-03&type=card_issuance&limit=50" \
    -H "x-contro-api-key: $CONTRO_API_KEY"
  ```

  ```typescript SDK (Node) theme={null}
  const records = await contro.usage.listRecords({
    period: "2026-03",
    type: "card_issuance",
    limit: 50,
  });
  ```

  ```python SDK (Python) theme={null}
  records = contro.usage.list_records(period="2026-03", type="card_issuance", limit=50)
  ```

  ```typescript TypeScript (fetch) theme={null}
  const records = await fetch(
    `${BASE_URL}/partner/usage/records?period=2026-03&type=card_issuance&limit=50`,
    { headers }
  ).then((r) => r.json());
  ```
</CodeGroup>

### Query parameters

| Parameter | Type | Description |
| - | - | - |
| `page` | integer | Page number (default `1`). |
| `limit` | integer | Items per page (1–100, default `20`). Example: `50` |
| `period` | string | Billing period in `YYYY-MM` format. Example: `"2026-03"`. |
| `type` | string | Filter by usage type. One of `card_issuance`, `transaction`, `monthly_fee`, `api_call`, `kyc`. |
| `from` | string | ISO 8601 start timestamp (inclusive) on `createdAt`. |
| `to` | string | ISO 8601 end timestamp (inclusive) on `createdAt`. |

### Response

```json theme={null}
{
  "data": [
    {
      "id": "usage_abc123",
      "type": "card_issuance",
      "amount": 5.00,
      "referenceId": "card_def456",
      "billingPeriod": "2026-03",
      "createdAt": "2026-03-15T10:30:00Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "cursor_xyz"
}
```

### Record fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Usage record ID. Example: `"usage_abc123"` |
| `type` | string | Usage type. One of `card_issuance`, `transaction`, `monthly_fee`, `api_call`, `kyc` |
| `amount` | number | Cost for this operation in USD. Example: `5.00` |
| `referenceId` | string | ID of the related resource (card, transaction, or cardholder). Example: `"card_def456"` |
| `billingPeriod` | string | Billing period in `YYYY-MM` format. Example: `"2026-03"` |
| `createdAt` | string | ISO 8601 creation timestamp. Example: `"2026-03-15T10:30:00Z"` |