---
title: "The team's usage and cost: CPU, memory, bandwidth, storage and build minutes per day, the plan's limits with their use, the estimated cost of the billing period on paid plans, what each project used, and the warnings at 80 % and 100 % that are on now"
method: GET
path: "/usage/report"
tags: ["Usage"]
---

# The team's usage and cost: CPU, memory, bandwidth, storage and build minutes per day, the plan's limits with their use, the estimated cost of the billing period on paid plans, what each project used, and the warnings at 80 % and 100 % that are on now

`GET /usage/report`

## Request

- Base URL: `https://hostingsurge.com/api/v1`
- URL: `https://hostingsurge.com/api/v1/usage/report`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `__Host-hs_session`

## Query parameters

- `orgId` string
- `range` '7d' | '30d'
- `lang` 'en' | 'sv'

## Response `200`

Usage

- object
  - `organizationId` string, uuid, required
  - `range` '7d' | '30d', required
  - `from` string, required: UTC day, YYYY-MM-DD
  - `to` string, required: UTC day, YYYY-MM-DD
  - `generatedAt` string, required: ISO-8601 timestamp
  - `planId` 'free' | 'pro' | 'business', required
  - `period` object, required
    - `start` string, required: ISO-8601 timestamp
    - `end` string, required: ISO-8601 timestamp
    - `source` 'subscription' | 'calendar_month', required
  - `days` object[], required
    - `day` string, required: UTC day, YYYY-MM-DD
    - `cpuCores` number, nullable, required: average vCPU in use over the day (measured minutes over the whole day, or the part of today that has passed); null: nothing was measured
    - `cpuCoresPeak` number, nullable, required
    - `memoryBytes` number, nullable, required: average memory in use over the day, like cpuCores
    - `memoryBytesPeak` number, nullable, required
    - `bandwidthBytes` number, nullable, required: bytes the proxy served for the project's addresses; null: not measured
    - `requests` number, nullable, required: requests the proxy logged (successful and not-modified answers)
    - `storageBytes` number, nullable, required: files in volumes plus database data, as measured that day; null: nothing measured
    - `buildMinutes` number, required: build minutes of builds started that day, each rounded up to a whole minute
  - `totals` object, required
    - `cpuCoreHours` number, nullable, required: vCPU-hours used in the range
    - `memoryGbHours` number, nullable, required: GB-hours of memory used in the range
    - `bandwidthBytes` number, nullable, required
    - `requests` number, nullable, required
    - `storageBytes` number, nullable, required: the newest storage measurement in the range
    - `buildMinutes` number, required
  - `limits` object[], required: the plan's limits for the billing period, with usage and state
    - `metric` 'projects' | 'databases' | 'seats' | 'buildMinutes' | 'bandwidthGb' | 'storageGb' | 'aiCredits' | 'emailsPerDay' | 'emailsPerMonth', required
    - `unit` 'count' | 'minutes' | 'gb' | 'credits', required
    - `label` string, required
    - `measured` boolean, required: false: no data source yet ("not metered yet"); used is then null
    - `used` number, nullable, required
    - `limit` number, nullable, required: included amount or allowance; null = unlimited
    - `cap` number, nullable, required: hard cap the team set (build minutes); null = none
    - `enforcedAt` 'create' | 'deploy' | 'builder' | 'send' | 'none', required: send: transactional email, refused with rate_limited once the quota is used (emailsPerDay resets 00:00 UTC, emailsPerMonth with the period)
    - `percent` number, nullable, required: used / limit in percent (rounded), null when unlimited or unmeasured
    - `state` 'ok' | 'warning' | 'reached' | 'over', required: warning ≥ 80%, reached ≥ 100%, over: beyond the included amount and billed
    - `overage` object, nullable, required
      - `quantity` number, required
      - `unitAmountDecimal` string, required
      - `currency` string, required
      - `estimatedAmount` integer, required: minor units (cents)
  - `teamResources` object, required: CPU and memory given to every project and database, against the team-wide cap of the plan (null: none)
    - `allocatedCpus` number, required
    - `allocatedMemoryMb` number, required
    - `totalCpus` number, nullable, required
    - `totalMemoryMb` number, nullable, required
  - `cost` object, nullable, required: null: the cost could not be computed right now, or the caller may not see it (costVisible)
    - `kind` 'free' | 'paid' | 'trial' | 'granted' | 'unlimited', required: free: the Free plan, nothing to pay; granted: a plan given by Hostingsurge without a subscription; unlimited: a team without limits; trial: nothing is charged until the trial ends
    - `planId` 'free' | 'pro' | 'business', required
    - `planName` string, required
    - `interval` 'month' | 'year' | 'null', nullable, required
    - `currency` string, required
    - `base` integer, required: the plan's price for the period
    - `overage` object[], required
      - `metric` 'projects' | 'databases' | 'seats' | 'buildMinutes' | 'bandwidthGb' | 'storageGb' | 'aiCredits' | 'emailsPerDay' | 'emailsPerMonth', required
      - `included` number, required
      - `used` number, required
      - `projected` number, required: usage at the end of the period at the pace so far
      - `quantity` number, required: projected usage beyond the included amount
      - `unitAmountDecimal` string, required
      - `amount` integer, required: minor units of `currency` (cents, öre, …), before tax
    - `total` integer, required: base + projected overage, before tax
    - `periodStart` string, required: ISO-8601 timestamp
    - `periodEnd` string, required: ISO-8601 timestamp
    - `trialEndsAt` string, nullable, required: ISO-8601 timestamp
    - `endsAtPeriodEnd` boolean, required: the subscription ends at the end of this period
    - `cap` number, nullable, required: the team's own build-minute cap (builds stop there); null: none
  - `costVisible` boolean, required: the caller has billing:read: owners, admins and billing members see the cost, others do not
  - `canUpgrade` boolean, required: the caller can change the plan (billing:write) and the team has limits to raise
  - `unlimited` boolean, required: a team without plan limits (the platform's own): no warnings and nothing to upgrade
  - `projects` object[], required: projects the caller can see that used something in the range, busiest first
    - `projectId` string, uuid, nullable, required: null: resources outside any project (standalone databases)
    - `name` string, nullable, required
    - `kind` string, nullable, required
    - `deleted` boolean, required
    - `totals` object, required
      - `cpuCoreHours` number, nullable, required: vCPU-hours used in the range
      - `memoryGbHours` number, nullable, required: GB-hours of memory used in the range
      - `bandwidthBytes` number, nullable, required
      - `requests` number, nullable, required
      - `storageBytes` number, nullable, required: the newest storage measurement in the range
      - `buildMinutes` number, required
  - `hiddenProjects` integer, required: projects the caller cannot see: counted in the team figures only
  - `alerts` object[], required
    - `scope` 'team' | 'project', required
    - `metric` union, required: team: a plan limit (buildMinutes, storageGb, …); project: cpu, memory or disk
      - 'projects' | 'databases' | 'seats' | 'buildMinutes' | 'bandwidthGb' | 'storageGb' | 'aiCredits' | 'emailsPerDay' | 'emailsPerMonth'
      - 'cpu' | 'memory' | 'disk'
    - `level` union, required: 80: getting close; 100: at or over the limit
      - 80
      - 100
    - `percent` number, nullable, required
    - `used` number, nullable, required
    - `limit` number, nullable, required
    - `unit` 'count' | 'minutes' | 'gb' | 'credits' | 'bytes' | 'cores', required
    - `projectId` string, uuid, nullable, required
    - `projectName` string, nullable, required
    - `subjectKind` 'project' | 'database' | 'volume' | 'null', nullable, required
    - `subjectId` string, uuid, nullable, required
    - `subjectName` string, nullable, required
    - `since` string, nullable, required: ISO-8601 timestamp
    - `billed` boolean, required: usage beyond the included amount is billed (paid plans), not stopped
  - `sources` object, required
    - `resources` object, required
      - `collecting` boolean, required: the CPU/memory collector reported in the last 5 minutes
      - `lastReportAt` string, nullable, required: ISO-8601 timestamp
    - `bandwidth` object, required
      - `measured` boolean, required: the proxy logs response sizes, the collector reported them in the last 7 days, and the team's own requests in the range were not all logged without a size
      - `partial` boolean, required: some of the team's requests in the range were logged without a size: the bytes are a lower bound
      - `lastReportAt` string, nullable, required: ISO-8601 timestamp
      - `sizedAt` string, nullable, required: ISO-8601 timestamp
    - `storage` object, required
      - `lastSnapshotAt` string, nullable, required: ISO-8601 timestamp

## Other responses

- `400`: Invalid request (code invalid_request)
- `401`: Missing or invalid session/token (code unauthorized)
- `403`: Authenticated but not permitted (code forbidden; needs projects:read)
- `404`: Not found or not visible to the caller (code not_found)
- `429`: Too many requests (code rate_limited); see Retry-After

---

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