> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instacloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get 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.



## OpenAPI

````yaml /openapi/project.json get /projects/{projectId}/database/insight
openapi: 3.1.0
info:
  title: InstaCloud API — Project level
  version: 0.1.0
  description: >-
    Endpoints under `/projects/{projectId}`: branches, services, deploys,
    secrets, databases, storage, cron, observability, governance. Callable with
    any token whose binding covers the project.


    Generated from the platform's own OpenAPI document
    (https://api.instacloud.com/openapi.json); see the [API
    overview](/reference/api/overview) for authentication and token scopes.
servers:
  - url: https://api.instacloud.com
    description: InstaCloud
security:
  - bearerAuth: []
tags:
  - name: Projects
    description: Projects inside an organization.
  - name: Branches
    description: >-
      Branch environments of a project: isolated database, storage and compute
      per branch.
  - name: Services
    description: 'Services on a branch: compute, postgres, storage and managed databases.'
  - name: Deploy
    description: Deploy an image or a source to a compute service.
  - name: Compute
    description: Build output of a compute service.
  - name: Secrets
    description: User secrets, service credentials and how they bind into compute env.
  - name: Database
    description: Postgres databases, extensions, credentials and ad-hoc SQL.
  - name: Storage
    description: Objects in a storage service.
  - name: Backups
    description: Database backups and restores.
  - name: Cron
    description: Scheduled HTTP calls against a service or an external URL.
  - name: Observability
    description: Logs, metrics, deploy events and database insight.
  - name: Governance
    description: Per-project agent policy and the approval queue.
  - name: Audit
    description: The project's event timeline, including agent-ingested events.
  - name: Domains
    description: >-
      Domains bought through InstaCloud, bring-your-own zones and their DNS
      records.
  - name: Billing
    description: Usage, cycles, invoices and credits.
  - name: Templates
    description: Deploy a template into a project.
paths:
  /projects/{projectId}/database/insight:
    get:
      tags:
        - Observability
      summary: Get database insight
      description: >-
        **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.
      operationId: getDatabaseInsight
      parameters:
        - schema:
            type: string
          in: query
          name: branch
          required: false
          description: branch name (default branch if omitted)
        - schema:
            type: string
          in: query
          name: group
          required: false
          description: 'postgres service name (default: the sole postgres service)'
        - schema:
            format: uuid
            type: string
          in: path
          name: projectId
          required: true
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DbInsight'
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    DbInsight:
      type: object
      properties:
        collected:
          description: >-
            false = suspended instance or provider without the capability;
            sections are structural zeros
          type: boolean
        sizes:
          type: object
          properties:
            databaseBytes:
              type: number
            tablesBytes:
              type: number
            indexesBytes:
              type: number
            walBytes:
              type: number
          required:
            - databaseBytes
            - tablesBytes
            - indexesBytes
            - walBytes
        tables:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              liveRows:
                type: number
              dataBytes:
                type: number
              indexBytes:
                type: number
              seqScans:
                type: number
              idxScans:
                type: number
            required:
              - name
              - liveRows
              - dataBytes
              - indexBytes
              - seqScans
              - idxScans
        vacuum:
          type: object
          properties:
            totalDeadRows:
              type: number
            tables:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  deadRows:
                    type: number
                  deadPct:
                    description: dead / (dead + live), 0..100
                    type: number
                  lastVacuum:
                    description: last manual or auto vacuum (UTC); omitted = never
                    type: string
                  xidAge:
                    type: number
                required:
                  - name
                  - deadRows
                  - deadPct
                  - xidAge
          required:
            - totalDeadRows
            - tables
        unusedIndexes:
          description: never-scanned indexes, excluding constraint-backing ones
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              table:
                type: string
              sizeBytes:
                type: number
              scans:
                type: number
            required:
              - name
              - table
              - sizeBytes
              - scans
        note:
          description: present when the provider serves no insight at all
          type: string
      required:
        - collected
        - sizes
        - tables
        - vacuum
        - unusedIndexes
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Session access JWT or an API token (`insta_<prefix>_<secret>`).

````