# List relationships

> Lists the Users you follow or hide, newest first.

`GET /relationships` on `https://api.mediux.io`

Each row embeds the target's `id`, `username` and `avatar`, so no profile lookup is needed. A banned, hidden or deleted User is left out. Pages default to 50 and hold at most 100. Pass `meta.nextCursor` as `after` to continue.

## Authorization

OAuth 2 bearer token in the `Authorization` header. Required permission: `relationships:read`.

## Parameters

- `kind` (query, string): Only `follow` or only `hide`.
- `after` (query, string): The `meta.nextCursor` from the previous page.
- `limit` (query, string): Page size, 1 to 100. Defaults to 50.

## Responses

### 200

A page of relationships.

- `data` (array of object, required)
  - `kind` (string, required): One of "follow", "hide".
  - `target` (object, required)
    - `id` (string (uuid), required)
    - `username` (string, required)
    - `avatar` (object, nullable, required)
      - `id` (string (uuid), required): Stable image ID, a lowercase UUID. Variant filenames use the same ID.
      - `extension` (string, required): Extension of the Original, such as `png`.
  - `createdAt` (string, required): ISO 8601 UTC instant with milliseconds, such as `2026-11-14T15:03:02.000Z`.
- `meta` (object, required)
  - `limit` (integer, required)
  - `nextCursor` (string, nullable, required)

### 400

The request is malformed or failed validation. Inspect `error.code` and `error.issues`.

### 401

The access token is missing (`auth.required`), or invalid, expired or revoked (`auth.invalidToken`).

### 403

The token lacks the required App Permission (`auth.insufficientScope`, with `details.required`), or the account or connection may not do this (`auth.forbidden`).

### 429

Too many requests. Wait the `Retry-After` seconds before trying again.

### 503

Temporarily unavailable. Check the outcome before retrying a write.

## Example response (200)

```json
{
  "data": [
    {
      "kind": "follow",
      "target": {
        "id": "2a49a110-dfa5-4411-8910-cc5cc3f1bc31",
        "username": "AlanShore60607",
        "avatar": null
      },
      "createdAt": "2026-11-19T11:52:42.532Z"
    }
  ],
  "meta": {
    "limit": 50,
    "nextCursor": null
  }
}
```

## Paging through relationships

A user can follow or hide another user, and each target has at most one
relationship. Every row embeds the target's public identity, so there is no
profile lookup per row. Keep requesting with `after` set to the previous
response's `meta.nextCursor` until it is `null`:

```json
{
  "data": [
    {
      "kind": "follow",
      "target": {
        "id": "USER_UUID",
        "username": "alice",
        "avatar": { "id": "AVATAR_UUID", "extension": "png" }
      },
      "createdAt": "2026-11-15T01:00:03.123Z"
    }
  ],
  "meta": { "limit": 50, "nextCursor": null }
}
```

`avatar` is `null` when the user has none. A banned, hidden or deleted user is
left out of the list. Change a relationship with
[Follow or hide a User](https://docs-preview.mediux.io/api/reference/relationships/set.md) and
[Clear a relationship](https://docs-preview.mediux.io/api/reference/relationships/clear.md). Reading needs
`relationships:read`; changing needs `relationships:manage`.
