ClientOptions

Configuration options for the Notion API client

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: undefined

Type: import("node:http").Agent

Example:

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,
})

Related Types

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

• Client - The main client class
• Error Handling - Learn about error types and retry behavior