# Get project app utilisation

`GET https://api.instacloud.com/projects/{projectId}/utilisation`

**Token scope:** `account` · `org` · `project` — read-only tokens allowed.

Per-app actual-vs-allocated compute utilisation over a window (default current cycle)

Quantities, not costs: the actual-consumption meters are collected at $0, so a cost-based ratio would read 0% for every app. `utilisation` is null when nothing was allocated in the window, which is not the same as 0% — the collector may simply not have run.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | `integer` | no | unix seconds (default current cycle start) |
| `to` | query | `integer` | no | unix seconds (default current cycle end) |
| `projectId` | path | `string` | yes |  |

## Response 200

Default Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | `integer` | no |  |
| `to` | `integer` | no |  |
| `apps` | `object[]` | no |  |
| `apps.app` | `string` | no |  |
| `apps.resourceId` | `string` | no |  |
| `apps.cpu` | `object` | no |  |
| `apps.cpu.allocated` | `number \| null` | no | the ceiling that was billed, in `unit`. NULL means no allocation was recorded in this window — not that nothing was allocated. |
| `apps.cpu.actual` | `number \| null` | no | what the app actually consumed, same unit. NULL means not measured in this window — not zero. |
| `apps.cpu.unit` | `string` | no |  |
| `apps.cpu.utilisation` | `number \| null` | no | actual / allocated; null when either side is unknown |
| `apps.cpu.suspect` | `boolean` | no | actual exceeds allocation, which is physically impossible — the stored rows are wrong. Excluded from totals. |
| `apps.cpu.unmetered` | `boolean` | no | the app exists but the collector produced no rows at all for it in this window — neither allocation nor reading. Worse than an absent reading: nothing bounds how much of the fleet is missing. |
| `apps.ram` | `object` | no |  |
| `apps.ram.allocated` | `number \| null` | no | the ceiling that was billed, in `unit`. NULL means no allocation was recorded in this window — not that nothing was allocated. |
| `apps.ram.actual` | `number \| null` | no | what the app actually consumed, same unit. NULL means not measured in this window — not zero. |
| `apps.ram.unit` | `string` | no |  |
| `apps.ram.utilisation` | `number \| null` | no | actual / allocated; null when either side is unknown |
| `apps.ram.suspect` | `boolean` | no | actual exceeds allocation, which is physically impossible — the stored rows are wrong. Excluded from totals. |
| `apps.ram.unmetered` | `boolean` | no | the app exists but the collector produced no rows at all for it in this window — neither allocation nor reading. Worse than an absent reading: nothing bounds how much of the fleet is missing. |
| `total` | `object` | no |  |
| `total.cpu` | `object` | no |  |
| `total.cpu.allocated` | `number \| null` | no | the ceiling that was billed, in `unit`. NULL means no allocation was recorded in this window — not that nothing was allocated. |
| `total.cpu.actual` | `number \| null` | no | what the app actually consumed, same unit. NULL means not measured in this window — not zero. |
| `total.cpu.unit` | `string` | no |  |
| `total.cpu.utilisation` | `number \| null` | no | actual / allocated; null when either side is unknown |
| `total.cpu.suspect` | `boolean` | no | actual exceeds allocation, which is physically impossible — the stored rows are wrong. Excluded from totals. |
| `total.cpu.unmetered` | `boolean` | no | the app exists but the collector produced no rows at all for it in this window — neither allocation nor reading. Worse than an absent reading: nothing bounds how much of the fleet is missing. |
| `total.ram` | `object` | no |  |
| `total.ram.allocated` | `number \| null` | no | the ceiling that was billed, in `unit`. NULL means no allocation was recorded in this window — not that nothing was allocated. |
| `total.ram.actual` | `number \| null` | no | what the app actually consumed, same unit. NULL means not measured in this window — not zero. |
| `total.ram.unit` | `string` | no |  |
| `total.ram.utilisation` | `number \| null` | no | actual / allocated; null when either side is unknown |
| `total.ram.suspect` | `boolean` | no | actual exceeds allocation, which is physically impossible — the stored rows are wrong. Excluded from totals. |
| `total.ram.unmetered` | `boolean` | no | the app exists but the collector produced no rows at all for it in this window — neither allocation nor reading. Worse than an absent reading: nothing bounds how much of the fleet is missing. |
| `total.cpuUnmeasuredApps` | `integer` | no | apps excluded from the cpu ratio for lack of a reading |
| `total.ramUnmeasuredApps` | `integer` | no | apps excluded from the ram ratio for lack of a reading |
| `total.cpuSuspectApps` | `integer` | no | apps excluded because actual exceeded allocation — impossible, so the stored rows are wrong |
| `total.ramSuspectApps` | `integer` | no | apps excluded because actual exceeded allocation — impossible, so the stored rows are wrong |
| `total.cpuUnmeteredApps` | `integer` | no | apps with no cpu metering rows at all — the ratio was computed over a smaller fleet than the real one |
| `total.ramUnmeteredApps` | `integer` | no | apps with no ram metering rows at all — the ratio was computed over a smaller fleet than the real one |

## Response 403

Default Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | `string` | yes |  |