> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://notion.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://notion.ferndocs.com/_mcp/server. # List comments GET https://api.notion.com/v1/comments Retrieves a list of un-resolved [Comment objects](/reference/comment-object) from a page or block. See [Pagination](https://developers.notion.com/reference/intro#pagination) for details about how to use a cursor to iterate through the list. ### Errors Each Public API endpoint can return several possible error codes. See the [Error codes section](https://developers.notion.com/reference/status-codes#error-codes) of the Status codes documentation for more information. Integration capabilities for reading and inserting comments are off by default. This endpoint requires an integration to have read comment capabilities. Attempting to call this endpoint without read comment capabilities will return an HTTP response with a 403 status code. For more information on integration capabilities, see the [capabilities guide](https://developers.notion.com/reference/capabilities). To update your integration settings, visit the [integration dashboard](https://www.notion.so/my-integrations). Reference: https://notion.ferndocs.com/reference/list-comments ## Request ### Query parameters - `block_id` (string, required) — Identifier for a Notion block or page - `start_cursor` (string, optional) — If supplied, this endpoint will return a page of results starting after the cursor provided. If not supplied, this endpoint will return the first page of results. - `page_size` (integer, optional) — The number of items from the full list desired in the response. Maximum: 100 ### Headers - `Notion-Version` (string, required) — The [API version](/reference/versioning) to use for this request. The latest version is `<>`. ## Response ### 200 200 - `object` (string, optional) - `results` (list of V1CommentsGetResponsesContentApplicationJsonSchemaResultsItems, optional) - `next_cursor` (any, optional) - `has_more` (boolean, optional, default: true) - `type` (string, optional) - `comment` (V1CommentsGetResponsesContentApplicationJsonSchemaComment, optional) ## Errors ### 403 Forbidden Error 403 - `object` (string, optional) - `status` (integer, optional, default: 0) - `code` (string, optional) - `message` (string, optional) ## Types ### V1CommentsGetResponsesContentApplicationJsonSchemaResultsItems - `object` (string, optional) - `id` (string, optional) - `parent` (V1CommentsGetResponsesContentApplicationJsonSchemaResultsItemsParent, optional) - `discussion_id` (string, optional) - `created_time` (string, optional) - `last_edited_time` (string, optional) - `created_by` (V1CommentsGetResponsesContentApplicationJsonSchemaResultsItemsCreatedBy, optional) - `rich_text` (list of V1CommentsGetResponsesContentApplicationJsonSchemaResultsItemsRichTextItems, optional) ### V1CommentsGetResponsesContentApplicationJsonSchemaComment ### V1CommentsGetResponsesContentApplicationJsonSchemaResultsItemsParent - `type` (string, optional) - `page_id` (string, optional) ### V1CommentsGetResponsesContentApplicationJsonSchemaResultsItemsCreatedBy - `object` (string, optional) - `id` (string, optional) ### V1CommentsGetResponsesContentApplicationJsonSchemaResultsItemsRichTextItems - `type` (string, optional) - `text` (V1CommentsGetResponsesContentApplicationJsonSchemaResultsItemsRichTextItemsText, optional) - `annotations` (V1CommentsGetResponsesContentApplicationJsonSchemaResultsItemsRichTextItemsAnnotations, optional) - `plain_text` (string, optional) - `href` (any, optional) ### V1CommentsGetResponsesContentApplicationJsonSchemaResultsItemsRichTextItemsText - `content` (string, optional) - `link` (any, optional) ### V1CommentsGetResponsesContentApplicationJsonSchemaResultsItemsRichTextItemsAnnotations - `bold` (boolean, optional, default: true) - `italic` (boolean, optional, default: true) - `strikethrough` (boolean, optional, default: true) - `underline` (boolean, optional, default: true) - `code` (boolean, optional, default: true) - `color` (string, optional) ## Examples **Response** ```json { "OK": { "value": "{\n \"object\": \"list\",\n \"results\": [\n {\n \"object\": \"comment\",\n \"id\": \"94cc56ab-9f02-409d-9f99-1037e9fe502f\",\n \"parent\": {\n \"type\": \"page_id\",\n \"page_id\": \"5c6a2821-6bb1-4a7e-b6e1-c50111515c3d\"\n },\n \"discussion_id\": \"f1407351-36f5-4c49-a13c-49f8ba11776d\",\n \"created_time\": \"2022-07-15T16:52:00.000Z\",\n \"last_edited_time\": \"2022-07-15T19:16:00.000Z\",\n \"created_by\": {\n \"object\": \"user\",\n \"id\": \"9b15170a-9941-4297-8ee6-83fa7649a87a\"\n },\n \"rich_text\": [\n {\n \"type\": \"text\",\n \"text\": {\n \"content\": \"Single comment\",\n \"link\": null\n },\n \"annotations\": {\n \"bold\": false,\n \"italic\": false,\n \"strikethrough\": false,\n \"underline\": false,\n \"code\": false,\n \"color\": \"default\"\n },\n \"plain_text\": \"Single comment\",\n \"href\": null\n }\n ]\n }\n ],\n \"next_cursor\": null,\n \"has_more\": false,\n \"type\": \"comment\",\n \"comment\": {}\n}" } } ``` **SDK Code** ```javascript Notion SDK for JavaScript const { Client } = require('@notionhq/client'); const notion = new Client({ auth: process.env.NOTION_API_KEY }); (async () => { const blockId = 'd40e767c-d7af-4b18-a86d-55c61f1e39a4'; const response = await notion.comments.list({ block_id: blockId }); console.log(response); })(); ``` ```python import requests url = "https://api.notion.com/v1/comments" querystring = {"block_id":"block_id"} headers = {"Notion-Version": "Notion-Version"} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.notion.com/v1/comments?block_id=block_id" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Notion-Version", "Notion-Version") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.notion.com/v1/comments?block_id=block_id") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Notion-Version"] = 'Notion-Version' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.notion.com/v1/comments?block_id=block_id") .header("Notion-Version", "Notion-Version") .asString(); ``` ```php request('GET', 'https://api.notion.com/v1/comments?block_id=block_id', [ 'headers' => [ 'Notion-Version' => 'Notion-Version', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.notion.com/v1/comments?block_id=block_id"); var request = new RestRequest(Method.GET); request.AddHeader("Notion-Version", "Notion-Version"); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Notion-Version": "Notion-Version"] let request = NSMutableURLRequest(url: NSURL(string: "https://api.notion.com/v1/comments?block_id=block_id")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```