---
title: "Monthly usage report"
method: GET
path: "/reports/usage"
tags: ["Partners"]
---

# Monthly usage report

`GET /reports/usage`

## Request

- Base URL: `https://faivelo.com/api/partner`
- URL: `https://faivelo.com/api/partner/reports/usage`
- Auth: HTTP bearer

One line per end customer for a calendar month: days live, domains, mailboxes, storage (latest nightly snapshot), sends, bounces and complaints. The input for invoicing your own clients. `format=csv` downloads a file. Defaults to the current month. Requires `partner:read`.

## Query parameters

- `month` string
- `format` 'json' | 'csv'

## Response `200`

The report

- object
  - `success` boolean
  - `data` PartnerUsageReport
    - `month` string
    - `from` string, date-time
    - `to` string, date-time
    - `generatedAt` string, date-time
    - `customers` PartnerUsageReportRow[]
      - `customerId` string
      - `email` string
      - `name` string, nullable
      - `companyName` string, nullable
      - `status` 'active' | 'paused' | 'suspended'
      - `createdAt` string, date-time
      - `daysLive` integer: Days in the month the account existed and was not suspended
      - `domains` integer
      - `mailboxes` integer
      - `plan` 'STARTER' | 'GROWTH' | 'PRO' | 'BUSINESS': The customer's highest domain plan
      - `domainPlans` object[]
        - `domain` string
        - `plan` 'STARTER' | 'GROWTH' | 'PRO' | 'BUSINESS'
        - `cents` integer: List price per month, before any volume discount
      - `monthlyCents` integer: What the customer's domains list at per month, before any volume discount
      - `seatCents` integer: Same as monthlyCents (named for the per-customer pricing before 18 Oct 2026)
      - `storageGb` number, nullable: Mail plus Drive, latest nightly snapshot
      - `sends` integer
      - `bounces` integer
      - `complaints` integer
      - `bounceRate` number: Fraction of sends, e.g. 0.012 is 1.2%
      - `complaintRate` number: Fraction of sends, e.g. 0.012 is 1.2%
    - `totals` object
      - `customers` integer
      - `mailboxes` integer
      - `domains` integer
      - `storageGb` number
      - `sends` integer
      - `bounces` integer
      - `complaints` integer
      - `byPlan` object: Domains per plan
        - `STARTER` integer
        - `GROWTH` integer
        - `PRO` integer
        - `BUSINESS` integer

## Other responses

- `400`: month must look like 2026-09
- `401`: Missing or invalid API key, or not a partner key
- `403`: The key lacks the required scope, or provisioning is refused (partner paused, customer cap reached)
- `404`: Not found, including any customer that is not yours
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/faivelo/apis/faivelo-api.md) · [All operations](https://skmtc.dev/faivelo/apis/faivelo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/faivelo/apis/faivelo-api/revisions/a7413ddea5d1?raw)