---
title: "One project's usage per day (CPU, memory, bandwidth, storage, build minutes) against what it runs with, its volumes, its share of the billing period's build minutes and its warnings"
method: GET
path: "/projects/{projectId}/usage"
tags: ["Usage"]
---

# One project's usage per day (CPU, memory, bandwidth, storage, build minutes) against what it runs with, its volumes, its share of the billing period's build minutes and its warnings

`GET /projects/{projectId}/usage`

## Request

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

## Path parameters

- `projectId` string, uuid, required

## Query parameters

- `range` '7d' | '30d'

## Response `200`

Usage

- object
  - `projectId` string, uuid, required
  - `organizationId` string, uuid, required
  - `name` string, 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
  - `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
  - `allocation` object, required: what the project runs with (Settings → Resources)
    - `cpus` number, required
    - `memoryMb` number, required
  - `planCeiling` object, nullable, required: the most the plan allows per project
    - `cpus` number, required
    - `memoryMb` number, required
  - `latest` object, nullable, required: the newest CPU/memory measurement of the last 10 minutes
    - `cpuCores` number, nullable, required
    - `memoryBytes` number, nullable, required
    - `at` string, required: ISO-8601 timestamp
  - `volumes` object[], required
    - `id` string, uuid, required
    - `name` string, required
    - `sizeGb` number, required
    - `usedBytes` number, nullable, required
    - `measuredAt` string, nullable, required: ISO-8601 timestamp
  - `period` object, required: this billing period: the project's build minutes, the whole team's and what the plan includes (null: unlimited)
    - `start` string, required: ISO-8601 timestamp
    - `end` string, required: ISO-8601 timestamp
    - `buildMinutes` number, required
    - `teamBuildMinutes` number, required
    - `includedBuildMinutes` number, nullable, required
  - `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: no warnings and nothing to upgrade
  - `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)