# List a user's external activities

`GET /user.activity.list`

## Description

Return every **currently live** external activity for a user — every
integration's rows, not only yours. Expired rows are omitted even
before the server reaper runs. Not paginated; ordered newest
`startedAt` first.

The map may show fewer entries than this list (the client projection
keeps the top three, always including at least one DND-flagged row).
`.list` is the source of truth for what is still live.

See [External activity](/docs/guides/user-activity) for display, DND,
TTL, and where indicators appear.

**Access:** Organization and Personal. Organization tokens may list
any user in the workspace. Personal tokens (OAuth or PAT) may list
only the token owner.

**Required scope:** `user:read.activity`. Personal Access Tokens skip
this check; personal-mode OAuth installs must still request the scope.

---

**OpenAPI Spec:** [chat-v1.json](https://developer.ro.am/chat-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `userId` | query | string | Yes | Target user. Bare or tagged UUID. Personal tokens may only pass their own user.  |

## Responses

### 200 - Live activities for the user. `activities` is an empty array when none are set.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `activities` | UserActivity[] | Yes |  |

**UserActivity** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `userId` | string | Yes | Bare UUID of the target user. |
| `externalId` | string | Yes | Caller-chosen id for this session, unique per integration and user (for example `justcall:call:CA123`). At most 128 Unicode code points.  |
| `display` | UserActivityDisplay | Yes |  |
| `dnd` | boolean | Yes | Whether this activity currently contributes Do Not Disturb on the user's assigned office.  |
| `startedAt` | string | Yes | When this session started (RFC3339). A heartbeat that omits `startedAt` keeps the original value.  |
| `expiresAt` | string | Yes | Server-stamped expiry (RFC3339). The indicator vanishes from the map and from `.list` once this instant has passed.  |

**UserActivityDisplay**:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `emoji` | string | Yes | Badge shown on the user's seat. Required. At most 16 Unicode code points, so ZWJ sequences (family emoji, flags) stay valid.  |
| `title` | string | Yes | Required hover-tooltip title. At most 140 Unicode code points. |
| `subtitle` | string | No | Optional supporting line after the title (for example the source app and a customer name). At most 140 Unicode code points. Omitted when empty.  |
| `color` | "blue" | "gold" | "gray" | "green" | "indigo" | "lime" | "orange" | "pink" | "purple" | "red" | "teal" | "yellow" | No | Curated glow palette name. Omit (or send empty) for a quiet badge-only activity. Unknown names are rejected at set time. Clients resolve the name to light/dark hex — hex is not part of the API. First- |


#### Example Response

```json
{
  "activities": [
    {
      "userId": "0cc74785-e31e-4403-aa5e-0cc7c1897e66",
      "externalId": "justcall:call:CA123",
      "display": {
        "emoji": "📞",
        "title": "On a customer call",
        "subtitle": "JustCall · Acme Corp",
        "color": "green"
      },
      "dnd": true,
      "startedAt": "2026-05-18T16:04:17.717Z",
      "expiresAt": "2026-05-18T16:34:17.717Z"
    }
  ]
}
```

### 400 - Bad request. Common causes:
- Missing `userId`


### 401 - Presented invalid authentication credentials.

### 403 - Forbidden. Common causes:
- Missing `user:read.activity` (OAuth / API key)
- Personal token targeting a user other than the owner (`access_denied`)


### 404 - User not found, or not in this workspace (`user_not_found`).

### 405 - An unsupported method was requested.

### 500 - An internal error occurred.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/api/user-activity-list*