0
# User Management
1

2
Retrieve information about users in the Notion workspace including the current authenticated user.
3

4
## Capabilities
5

6
### Retrieve User
7

8
Get a user by their ID, including profile information and type.
9

10
```typescript { .api }
11
/**
12
 * Retrieve a user by ID
13
 * @param args - User retrieval parameters
14
 * @returns Promise resolving to user object
15
 */
16
users.retrieve(args: GetUserParameters): Promise<GetUserResponse>;
17

18
interface GetUserParameters {
19
  /** ID of the user to retrieve */
20
  user_id: string;
21
}
22

23
type GetUserResponse = UserObjectResponse;
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
// Get a specific user
30
const user = await notion.users.retrieve({
31
  user_id: "user-id-here",
32
});
33

34
console.log(user.name); // User's name
35
console.log(user.type); // "person" or "bot"
36
if (user.type === "person") {
37
  console.log(user.person.email); // Email for person users
38
}
39
```
40

41
### List Users
42

43
Retrieve a list of all users in the workspace.
44

45
```typescript { .api }
46
/**
47
 * List all users in the workspace
48
 * @param args - User list parameters
49
 * @returns Promise resolving to list of users
50
 */
51
users.list(args: ListUsersParameters): Promise<ListUsersResponse>;
52

53
interface ListUsersParameters {
54
  /** Pagination cursor */
55
  start_cursor?: string;
56
  /** Page size (max 100) */
57
  page_size?: number;
58
}
59

60
type ListUsersResponse = {
61
  object: "list";
62
  results: UserObjectResponse[];
63
  next_cursor: string | null;
64
  has_more: boolean;
65
  type: "user";
66
  user: Record<string, unknown>;
67
};
68
```
69

70
**Usage Examples:**
71

72
```typescript
73
// Get all users
74
const users = await notion.users.list({});
75

76
console.log(users.results.length); // Number of users
77
users.results.forEach(user => {
78
  console.log(`${user.name} (${user.type})`);
79
});
80

81
// Paginated user listing
82
const usersPage = await notion.users.list({
83
  page_size: 50,
84
  start_cursor: "cursor-token",
85
});
86

87
// Get all users with pagination
88
let cursor: string | undefined;
89
let allUsers: UserObjectResponse[] = [];
90

91
do {
92
  const response = await notion.users.list({
93
    start_cursor: cursor,
94
  });
95
  
96
  allUsers.push(...response.results);
97
  cursor = response.next_cursor || undefined;
98
} while (cursor);
99
```
100

101
### Get Current User
102

103
Retrieve information about the currently authenticated user.
104

105
```typescript { .api }
106
/**
107
 * Get information about the current authenticated user
108
 * @param args - Current user parameters (empty)
109
 * @returns Promise resolving to current user object
110
 */
111
users.me(args: GetSelfParameters): Promise<GetSelfResponse>;
112

113
interface GetSelfParameters {
114
  // No parameters required
115
}
116

117
type GetSelfResponse = UserObjectResponse;
118
```
119

120
**Usage Examples:**
121

122
```typescript
123
// Get current user info
124
const currentUser = await notion.users.me({});
125

126
console.log(`Current user: ${currentUser.name}`);
127
console.log(`User type: ${currentUser.type}`);
128

129
if (currentUser.type === "bot") {
130
  console.log(`Bot owner: ${currentUser.bot.owner.type}`);
131
}
132
```
133

134
## Types
135

136
```typescript { .api }
137
type UserObjectResponse = PersonUserObjectResponse | BotUserObjectResponse;
138

139
interface PersonUserObjectResponse {
140
  object: "user";
141
  id: string;
142
  type: "person";
143
  name?: string;
144
  avatar_url?: string;
145
  person: {
146
    email?: string;
147
  };
148
}
149

150
interface BotUserObjectResponse {
151
  object: "user";
152
  id: string;
153
  type: "bot";
154
  name?: string;
155
  avatar_url?: string;
156
  bot: {
157
    owner: {
158
      type: "workspace";
159
      workspace: true;
160
    } | {
161
      type: "user";
162
      user: PartialUserObjectResponse;
163
    };
164
    workspace_name?: string;
165
  };
166
}
167

168
interface GroupObjectResponse {
169
  object: "user";
170
  id: string;
171
  type: "group";
172
  name?: string;
173
  avatar_url?: string;
174
  group: Record<string, unknown>;
175
}
176

177
interface PartialUserObjectResponse {
178
  object: "user";
179
  id: string;
180
}
181
```