---
title: "Retrieve a portion of a space tree."
method: GET
path: "/_matrix/client/v1/rooms/{roomId}/hierarchy"
tags: ["Spaces"]
---

# Retrieve a portion of a space tree.

`GET /_matrix/client/v1/rooms/{roomId}/hierarchy`

## Request

- Base URL: `https://matrix.org`
- URL: `https://matrix.org/_matrix/client/v1/rooms/{roomId}/hierarchy`
- Auth: one of:
  - API key in query parameter `access_token`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/matrix/apis/matrix-client-server-api/docs/_matrix/client/v1/rooms/:roomId/hierarchy/get.ts> (a function with typed inputs; its response is checked against the schema)

Paginates over the space tree in a depth-first manner to locate child rooms of a given space.

Where a child room is unknown to the local server, federation is used to fill in the details.
The servers listed in the `via` array should be contacted to attempt to fill in missing rooms.

Only [`m.space.child`](https://spec.matrix.org/v1.19/client-server-api/#mspacechild) state events of the room are considered.
Invalid child rooms and parent events are not covered by this endpoint.

## Path parameters

- `roomId` string, required

## Query parameters

- `suggested_only` boolean
- `limit` integer
- `max_depth` integer
- `from` string

## Response `200`

A portion of the space tree, starting at the provided room ID.

- object
  - `next_batch` string: A token to supply to `from` to keep paginating the responses. Not present when there are no further results.
  - `rooms` object[], required: The rooms for the current page, with the current filters. The server should return any rooms where at least one of the following conditions is true: * The requesting user is currently a member (their [room membership](#room-membership) is `join`). * The requesting user already has permission to join, i.e. one of the following: * The user's room membership is `invite`. * The room's [join rules](#mroomjoin_rules) are set to `public`. * The room's join rules are set to [`restricted`](#restricted-rooms), provided the user meets one of the specified conditions. * The room is "knockable" (the room's join rules are set to `knock`, or `knock_restricted`, in a room version that supports those settings). * The room's [`m.room.history_visibility`](#room-history-visibility) is set to `world_readable`.
    - `avatar_url` string, uri: The URL for the room's avatar, if one is set.
    - `canonical_alias` string, mx-room-alias: The canonical alias of the room, if any.
    - `guest_can_join` boolean, required: Whether guest users may join the room and participate in it. If they can, they will be subject to ordinary power level rules like any other user.
    - `join_rule` string: The room's join rule. When not present, the room is assumed to be `public`.
    - `name` string: The name of the room, if any.
    - `num_joined_members` integer, required: The number of members joined to the room.
    - `room_id` string, mx-room-id, required: The ID of the room.
    - `room_type` string: The `type` of room (from [`m.room.create`](https://spec.matrix.org/v1.19/client-server-api/#mroomcreate)), if any.
    - `topic` string: The plain text topic of the room. Omitted if no `text/plain` mimetype exists in [`m.room.topic`](https://spec.matrix.org/v1.19/client-server-api/#mroomtopic).
    - `world_readable` boolean, required: Whether the room may be viewed by users without joining.
    - `allowed_room_ids` string[]: If the room is a [restricted room](https://spec.matrix.org/v1.19/server-server-api/#restricted-rooms), these are the room IDs which are specified by the join rules. Empty or omitted otherwise.
    - `encryption` 'm.megolm.v1.aes-sha2': The encryption algorithm to be used to encrypt messages sent in the room.
    - `room_version` string: The version of the room.
    - `children_state` object[], required: The [`m.space.child`](https://spec.matrix.org/v1.19/client-server-api/#mspacechild) events of the space-room, represented as [Stripped State Events](https://spec.matrix.org/v1.19/client-server-api/#stripped-state) with an added `origin_server_ts` key. If the room is not a space-room, this should be empty.
      - `content` object, required: The `content` for the event.
      - `sender` string, mx-user-id, required: The `sender` for the event.
      - `state_key` string, required: The `state_key` for the event.
      - `type` string, required: The `type` for the event.
      - `origin_server_ts` integer, required: The `origin_server_ts` for the event.

## Other responses

- `400`: The request was invalid in some way. A meaningful `errcode` and description error text will be returned. Example reasons for rejection are: - The `from` token is unknown to the server. - `suggested_only` or `max_depth` changed during pagination.
- `403`: The user cannot view or peek on the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejection are: - The room is not set up for peeking. - The user has been banned from the room. - The room does not exist.
- `429`: This request was rate-limited.

---

[API](https://skmtc.dev/matrix/apis/matrix-client-server-api.md) - [All operations](https://skmtc.dev/matrix/apis/matrix-client-server-api/llms.txt) - [OpenAPI document](https://skmtc.dev/matrix/apis/matrix-client-server-api/revisions/c7fe4072c681?raw)