Notion API 페이지 조회

페이지 ID 하나만 알면 Notion에 저장된 페이지 정보를 API로 바로 가져올 수 있어요. 이번에 다룰 건 그중에서도 가장 기본이 되는 페이지 조회(Retrieve a page) 예요. 페이지의 속성(properties) 값을 읽어 오지만, 페이지 안에 실제로 적힌 콘텐츠(블록)는 돌려주지 않는다는 점만 처음에 짚고 넘어갈게요.

Notion의 페이지는 크게 두 종류로 나뉘는데, 조회 결과가 여기에 따라 달라져요.

페이지의 부모(parent)가 데이터베이스라면, 응답의 속성 값이 그 데이터베이스의 속성 스키마를 따릅니다.
페이지가 데이터베이스에 속하지 않으면 속성으로는 title 하나만 돌아와요.

콘텐츠 자체가 필요하면 별도의 블록 자식 조회(retrieve block children) 엔드포인트를 써야 해요.

출처: 문서

본문

핵심 기능: GET /v1/pages/{page_id}

페이지 조회는 page_id 하나를 경로 파라미터로 받는 간단한 GET 요청이에요. 응답에는 페이지 객체(Page object)가 담기고, 여기에는 페이지 속성이 포함돼요.

기본 요청 형태는 이렇게 됩니다.

curl --request GET \
  --url https://api.notion.com/v1/pages/{page_id} \
  --header 'Authorization: Bearer ***' \
  --header 'Notion-Version: <notion-version>'

같은 요청을 Python requests로 보내면 이렇게 되고요.

import requests

url = "https://api.notion.com/v1/pages/{page_id}"
headers = {
    "Notion-Version": "<notion-version>",
    "Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)

헤더와 파라미터

Authorization (필수): Bearer <token> 형태의 인증 헤더. <token> 자리에 내 인증 토큰을 넣어요.
Notion-Version (필수): 요청에 사용할 API 버전. 최신 버전은 2026-03-11예요.
page_id (경로 파라미터, 필수): 조회할 페이지의 ID.
filter_properties (쿼리 파라미터, 선택): 응답에 포함할 속성만 필터링하려고 속성 ID 목록을 넘겨요. 페이지에 없는 속성은 필터된 응답에 포함되지 않아요. 배열 최대 길이는 100.

응답 구조 (Page object)

성공하면 HTTP 200과 함께 페이지 객체가 돌아와요. 예시 응답을 보면 대략 이런 구조예요.

{
  "object": "page",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

실제 페이지 객체에는 properties를 비롯해 여러 필드가 포함됩니다. 주요 필드는 다음과 같아요.

object: 항상 "page".
id: 페이지의 고유 식별자(UUIDv4).
created_time / last_edited_time: 페이지가 만들어지고 수정된 시각(ISO 8601 문자열).
created_by / last_edited_by: 페이지를 만든/마지막으로 수정한 사용자.
in_trash: 페이지가 휴지통에 있는지 여부. (archived는 예전 필드로, in_trash와 항상 같은 값을 돌려줘요.)
icon / cover: 페이지 아이콘과 표지 이미지.
parent: 페이지의 부모 정보(부모 객체).
properties: 페이지의 속성 값. 부모가 데이터베이스면 해당 스키마를 따르고, 아니면 title만 있어요.
url / public_url: 페이지 URL. 웹에 공개된 경우에만 public_url에 값이 채워져요.

참고로 버전 2022-06-28부터는 properties에 속성 값 대신 속성 ID만 담겨요. 실제 값은 별도 페이지 속성 값 조회로 확인해야 해요.

페이지 조회의 한계와 오류

25개 참조 제한이 있어요. 이 엔드포인트는 속성당 최대 25개의 페이지·사람 참조만 정확하게 돌려줍니다. 속성에 25개가 넘는 참조가 들어 있으면 26번째부터는 Untitled, Anonymous로 나오거나 아예 빠질 수 있어요. 전체 참조 목록이 필요하면 각 속성 전용의 페이지 속성 조회(retrieve a page property) 엔드포인트를 써야 해요. 이 제한은 people, relation, rich_text, title 속성에 영향을 줘요. 특히 relation은 25개가 넘는 관련 페이지가 있으면 has_more가 true로 돌아와요.

연결 권한도 필요한데요, 이 엔드포인트는 연결(connection)에 콘텐츠 읽기(read content) 권한이 있어야 해요. 권한이 없으면 403 응답이 돌아와요.

오류 응답은 이런 식으로 옵니다.

{
  "object": "error",
  "message": "<string>",
  "code": "object_not_found",
  "status": 404,
  "additional_data": {}
}

페이지가 없거나 연결이 그 페이지에 접근 권한이 없으면 404.
요청 한도를 초과하면 400 또는 429.

각 상태 코드에 대한 자세한 내용은 상태 코드 문서의 Error codes 섹션을 참고하세요.

더 알아보기 (Learn more)

공식 문서