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

# List Sub-Orgs

> Retrieve a paginated list of sub-orgs, optionally filtered by name.

**GET** `/api/external/sub_orgs/?limit={limit}&cursor={cursor}&name={name}`

Returns the sub-orgs visible to the authenticated API user. Results are scoped to the organization, exclude deleted rows, and are ordered newest first by creation time, with ID as the tie-breaker.

## Query parameters

<ParamField query="name" type="string">
  Case-insensitive SQL-pattern match. Use `%PrimeVault%` to match names containing PrimeVault, or `PrimeVault%` for a prefix. `%` matches any sequence and `_` matches one character.
</ParamField>

<ParamField query="limit" type="integer">
  Page size. Default: 20; effective range: 1-100.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque cursor returned as `nextCursor`. Omit it or send an empty value for the first page.
</ParamField>

## Response

```typescript theme={null}
interface SubOrgListResponse {
  results: SubOrg[];
  nextCursor?: string | null;
  hasNext?: boolean;
}
```

## JavaScript SDK - read every page

```typescript theme={null}
import type { SubOrg } from "@primevault/js-api-sdk";

const subOrgs: SubOrg[] = [];
let cursor: string | null = null;

do {
  const page = await apiClient.getSubOrgs(
    { name: "%PrimeVault%" },
    20,
    cursor,
  );
  subOrgs.push(...page.results);
  cursor = page.nextCursor;
} while (cursor);
```

## Python SDK - read every page

```python theme={null}
from typing import List, Optional
from primevault_python_sdk.types import SubOrg

sub_orgs: List[SubOrg] = []
cursor: Optional[str] = None

while True:
    page = api_client.get_sub_orgs(
        {"name": "%PrimeVault%"}, limit=20, cursor=cursor
    )
    sub_orgs.extend(page.results)
    if not page.hasNext:
        break
    cursor = page.nextCursor
```

<RequestExample dropdown>
  ```json Request example theme={null}
  {
    "query": {
      "limit": 20,
      "name": "%PrimeVault%"
    }
  }
  ```

  ```bash cURL theme={null}
  # Sample only. Generate a new signed token for each request
  # (see Authentication). Tokens expire after 120 seconds.
  curl --request GET \
    --url "https://api.primevault.com/api/external/sub_orgs/?limit=20&name=%25PrimeVault%25" \
    --header "Authorization: Bearer <signed JWT>" \
    --header "Api-Key: <API key>" \
    --header "Accept: application/json"
  ```

  ```typescript JavaScript SDK theme={null}
  getSubOrgs(
    params?: Record<string, string>,
    limit?: number,
    cursor?: string | null,
  ): Promise<SubOrgListResponse>
  ```
</RequestExample>

<ResponseExample>
  ```json JSON example theme={null}
  {
    "results": [
      {
        "id": "a648fa0d-4ca9-4f4f-a520-7ef5e9db34eb",
        "orgId": "a30d5e99-7076-45da-a933-0d5642619340",
        "name": "PrimeVault customer",
        "controlMode": "MANAGED",
        "createdAt": "2026-09-14T12:00:00Z",
        "updatedAt": "2026-09-14T12:00:00Z",
        "isDeleted": false,
        "version": 1
      }
    ],
    "nextCursor": null,
    "hasNext": false
  }
  ```
</ResponseExample>

<Note>
  When `hasNext` is true, pass `nextCursor` unchanged into the next request. Keep the same name filter and page size while paging. An empty result is `results: []`, `nextCursor: null`, and `hasNext: false`. This response does not include a total count.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.