---
title: "List organisations"
method: GET
path: "/v2/organisations"
tags: ["Gateway GRPC"]
---

# List organisations

`GET /v2/organisations`

## Request

- Base URL: `https://api.cautio.in` (the document declares no server; this is the origin it was published from)
- URL: `https://api.cautio.in/v2/organisations`
- Auth: HTTP bearer

| Mode | Parameters | Result |
|------|------------|--------|
| Root organisations (default) | Omit both `parent_id` and `include_descendants` | Returns only root organisations visible to the current user |
| All accessible organisations | `include_descendants=true` and no `parent_id` | Returns all organisations the user can access under their roots |
| Direct children of a parent | Provide `parent_id`; omit `include_descendants` or set it to `false` | Returns only the direct children of the specified parent |
| All descendants of a parent | Provide `parent_id` and set `include_descendants=true` | Returns all descendants of the specified parent |

**Additional filters**

| Parameter | Description |
|-----------|-------------|
| `query` | Performs a case-insensitive substring search on organisation `display_name` |
| `ids` | May be provided alone (without any other query parameters) to fetch an explicit list of organisations by ID |

## Query parameters

- `limit` number
- `page` number
- `query` string
- `parent_id` string
- `include_descendants` boolean
- `include_ancestors` boolean
- `ids` string[]

## Response `200`

List of organisations

- GetOrganisationListingResponseDto
  - `items` OrganisationItemDto[], required
    - `id` string, required: Organisation id
    - `display_name` string, required: Display name of the organisation
    - `parent_id` string: Effective parent organisation id when accessible to the user; omitted when the physical parent exists but is inaccessible
    - `children_count` number: Number of direct child organisations visible to the user
    - `vehicle_count` number: Total number of vehicles in this organisation and its accessible sub-organisations
    - `is_setup` boolean, required: Whether first-time setup is complete for this organisation
    - `path` OrganisationDto[]: Visible ancestor chain from top-level visible ancestor to this organisation
      - `id` string, required: Organisation id
      - `display_name` string, required: Display name of the organisation
      - `parent_id` string: Effective parent organisation id when accessible to the user; omitted when the physical parent exists but is inaccessible
      - `children_count` number: Number of direct child organisations visible to the user
      - `vehicle_count` number: Total number of vehicles in this organisation and its accessible sub-organisations
      - `is_setup` boolean, required: Whether first-time setup is complete for this organisation
      - `path` OrganisationDto[]: Visible ancestor chain from top-level visible ancestor to this organisation
    - `children` object: List of child organisations
  - `pagination` PaginationResponseDto, required
    - `page` number, required: Current page number
    - `limit` number, required: Number of items per page
    - `total` number, required: Total number of items
    - `has_next` boolean, required: Whether there is a next page
    - `has_prev` boolean, required: Whether there is a previous page

---

[API](https://skmtc.dev/cautio/apis/cautio-api.md) - [All operations](https://skmtc.dev/cautio/apis/cautio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cautio/apis/cautio-api/revisions/214e6d1d2b6c?raw)