Skip to main content
GET
/
v1
/
users
TypeScript SDK
import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.users.list({
  start_cursor: undefined,
  page_size: 10
})
{
  "type": "<string>",
  "user": {},
  "object": "<string>",
  "next_cursor": "<string>",
  "has_more": true,
  "results": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "object": "<string>",
      "name": "<string>",
      "avatar_url": "<string>",
      "type": "<string>",
      "person": {
        "email": "<string>"
      }
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://developers.notion.com/llms.txt

Use this file to discover all available pages before exploring further.

Guests are not included in the response. If you already know a guest’s ID, Retrieve a user can return that guest when they belong to the connected workspace. See Pagination for details about how to use a cursor to iterate through the list. The API does not guarantee a particular sort order for returned users.
Personal access tokens cannot list workspace users. Use Retrieve token’s bot user to retrieve the PAT creator, or Retrieve a user with that user’s ID.

​
Errors

Each Public API endpoint can return several possible error codes. See the Error codes section of the Status codes documentation for more information.
The API does not currently support filtering users by their email and/or name.
Connection capabilitiesThis endpoint requires a connection to have user information capabilities. Attempting to call this API without user information capabilities will return an HTTP response with a 403 status code. For more information on connection capabilities, see the capabilities guide.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Notion-Version
enum<string>
required

The API version to use for this request. The latest version is 2026-03-11.

Available options:
2026-03-11

Query Parameters

​
start_cursor
string
​
page_size
number

Response

​
type
string
required
Allowed value: "user"
​
user
object
required
​
object
string
required
Allowed value: "list"
​
next_cursor
string | null
required
​
has_more
boolean
required
​
results
(Person · object | Bot · object)[]
required