Skip to main content
The ClientOptions interface defines all configuration options that can be passed to the Client constructor.

​
Type Definition

type ClientOptions = {
  auth?: string
  timeoutMs?: number
  baseUrl?: string
  logLevel?: LogLevel
  logger?: Logger
  notionVersion?: string
  fetch?: SupportedFetch
  agent?: Agent
  retry?: RetryOptions | false
}

​
Properties

​
auth
string
The Notion API token or OAuth access token for authentication.Default: undefined (must be provided per-request or set on the client)
const notion = new Client({
  auth: process.env.NOTION_TOKEN,
})
​
logLevel
LogLevel
The minimum log level for console output. Use LogLevel.DEBUG, LogLevel.INFO, LogLevel.WARN, or LogLevel.ERROR.Default: LogLevel.WARN
import { Client, LogLevel } from "@notionhq/client"

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  logLevel: LogLevel.DEBUG,
})
​
timeoutMs
number
Request timeout in milliseconds.Default: 60000 (60 seconds)
const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  timeoutMs: 30000, // 30 seconds
})
​
baseUrl
string
The base URL for the Notion API. Useful for testing or proxying requests.Default: "https://api.notion.com"
const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  baseUrl: "https://api-proxy.example.com",
})
​
logger
Logger
Custom logger function that receives log level, message, and extra information.Default: makeConsoleLogger("@notionhq/client")Type signature:
type Logger = (
  level: LogLevel,
  message: string,
  extraInfo: Record<string, unknown>
) => void
Example:
const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  logger: (level, message, extraInfo) => {
    console.log(`[${level}] ${message}`, extraInfo)
  },
})
​
notionVersion
string
The Notion API version to use. This sets the Notion-Version header.Default: "2025-09-03" (from Client.defaultNotionVersion)
const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  notionVersion: "2025-09-03",
})
​
fetch
SupportedFetch
Custom fetch implementation. Useful for testing or using alternative fetch libraries.Default: fetch (global fetch)Type signature:
type SupportedFetch = (
  url: string,
  init?: SupportedRequestInit
) => Promise<SupportedResponse>
Example:
import nodeFetch from "node-fetch"

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  fetch: nodeFetch as any,
})
​
agent
Agent
HTTP agent for Node.js requests. Silently ignored in browser environments.Default: undefinedType: import("node:http").AgentExample:
import { Agent } from "node:http"

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  agent: new Agent({ keepAlive: true }),
})
​
retry
RetryOptions | false
Configuration for automatic retries on rate limit (429) and server errors. Set to false to disable retries entirely.Default: { maxRetries: 2, initialRetryDelayMs: 1000, maxRetryDelayMs: 60000 }RetryOptions type:
type RetryOptions = {
  maxRetries?: number           // Default: 2
  initialRetryDelayMs?: number  // Default: 1000
  maxRetryDelayMs?: number      // Default: 60000
}
Retry behavior:
  • Rate limits (429) are always retried for all HTTP methods
  • Server errors (500, 503) are only retried for idempotent methods (GET, DELETE)
  • Uses retry-after header when present, otherwise exponential back-off with jitter
Example - custom retry settings:
const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  retry: {
    maxRetries: 3,
    initialRetryDelayMs: 2000,
    maxRetryDelayMs: 30000,
  },
})
Example - disable retries:
const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  retry: false,
})

​
LogLevel

enum LogLevel {
  DEBUG = "debug",
  INFO = "info",
  WARN = "warn",
  ERROR = "error",
}

​
RetryOptions

type RetryOptions = {
  maxRetries?: number           // Default: 2
  initialRetryDelayMs?: number  // Default: 1000
  maxRetryDelayMs?: number      // Default: 60000
}

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us