---
title: "Get Workspace Neon Roles"
method: GET
path: "/api/v1/internal/workspaces/{workspace_id}/neon-roles"
tags: ["internal", "workspaces"]
---

# Get Workspace Neon Roles

`GET /api/v1/internal/workspaces/{workspace_id}/neon-roles`

Branch-scoped Neon role consumption.

The default read serves the stored census plus a fresh keep-set — app-DB
only, so it never wakes the branch. ``refresh=true`` reads ``pg_roles``
live via the pooled sandbox seam (waking a suspended branch) and stores
the new census; the busy/unreachable 503s can only occur on that path.

## Path parameters

- `workspace_id` string, uuid, required

## Query parameters

- `refresh` boolean

## Response `200`

Successful Response

- AdminNeonRoleSummaryResponse — Branch-scoped Neon role consumption for the internal workspace page. Counts are null when the workspace has no Neon sandbox provisioned — and on a cached response when no census has been stored yet (``read_at`` null distinguishes never-read from unprovisioned via ``provisioned``). ``from_cache`` is true when the response never touched the branch; ``read_at`` stamps when the branch was actually read. ``on_shared_self_serve_project`` is null when it cannot be determined.
  - `provisioned` boolean, required
  - `role_count` integer, nullable, required
  - `role_cap` integer, required
  - `project_role_count` integer, nullable, required
  - `live_project_role_count` integer, nullable, required
  - `orphan_role_count` integer, nullable, required
  - `live_project_count` integer, nullable, required
  - `on_shared_self_serve_project` boolean, nullable, required
  - `read_at` string, date-time, nullable, required
  - `from_cache` boolean, required

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-10** `97ae7fd86d44` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/maia-analytics/apis/maia-api/changes/api/v1/internal/workspaces/:workspace_id/neon-roles/get.md)

---

[API](https://skmtc.dev/maia-analytics/apis/maia-api.md) · [All operations](https://skmtc.dev/maia-analytics/apis/maia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/maia-analytics/apis/maia-api/revisions/bb508e935174?raw)