# Get database insight

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

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

Deep database health: size breakdown, per-table stats, vacuum health, unused indexes. Read-only; insta-db-backed services answer without waking a suspended instance.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `branch` | query | `string` | no | branch name (default branch if omitted) |
| `group` | query | `string` | no | postgres service name (default: the sole postgres service) |
| `projectId` | path | `string` | yes |  |

## Response 200

Default Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `collected` | `boolean` | yes | false = suspended instance or provider without the capability; sections are structural zeros |
| `sizes` | `object` | yes |  |
| `sizes.databaseBytes` | `number` | yes |  |
| `sizes.tablesBytes` | `number` | yes |  |
| `sizes.indexesBytes` | `number` | yes |  |
| `sizes.walBytes` | `number` | yes |  |
| `tables` | `object[]` | yes |  |
| `tables.name` | `string` | yes |  |
| `tables.liveRows` | `number` | yes |  |
| `tables.dataBytes` | `number` | yes |  |
| `tables.indexBytes` | `number` | yes |  |
| `tables.seqScans` | `number` | yes |  |
| `tables.idxScans` | `number` | yes |  |
| `vacuum` | `object` | yes |  |
| `vacuum.totalDeadRows` | `number` | yes |  |
| `vacuum.tables` | `object[]` | yes |  |
| `vacuum.tables.name` | `string` | yes |  |
| `vacuum.tables.deadRows` | `number` | yes |  |
| `vacuum.tables.deadPct` | `number` | yes | dead / (dead + live), 0..100 |
| `vacuum.tables.lastVacuum` | `string` | no | last manual or auto vacuum (UTC); omitted = never |
| `vacuum.tables.xidAge` | `number` | yes |  |
| `unusedIndexes` | `object[]` | yes | never-scanned indexes, excluding constraint-backing ones |
| `unusedIndexes.name` | `string` | yes |  |
| `unusedIndexes.table` | `string` | yes |  |
| `unusedIndexes.sizeBytes` | `number` | yes |  |
| `unusedIndexes.scans` | `number` | yes |  |
| `note` | `string` | no | present when the provider serves no insight at all |

## Response 404

Default Response

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

## Response 502

Default Response

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