curl --request GET \
--url https://api.notion.com/v1/agents \
--header 'Authorization: Bearer <token>' \
--header 'Notion-Version: <notion-version>'import requests
url = "https://api.notion.com/v1/agents"
headers = {
"Notion-Version": "<notion-version>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'Notion-Version': '<notion-version>', Authorization: 'Bearer <token>'}
};
fetch('https://api.notion.com/v1/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.notion.com/v1/agents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Notion-Version: <notion-version>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.notion.com/v1/agents"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Notion-Version", "<notion-version>")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.notion.com/v1/agents")
.header("Notion-Version", "<notion-version>")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.notion.com/v1/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Notion-Version"] = '<notion-version>'
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"object": "list",
"type": "agent",
"results": [
{
"object": "agent",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent_type": "notion_ai",
"name": "<string>",
"description": "<string>",
"instructions_page_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"icon": {
"type": "emoji",
"emoji": "😀"
},
"version": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"number": 123,
"published_at": "<string>"
},
"agent_version": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"number": 123,
"published_at": "<string>"
},
"model": {
"mode": "auto"
},
"connections": [
{
"type": "notion",
"name": "<string>",
"account": null,
"permissions": [
{
"target": {
"type": "page",
"id": "<string>"
},
"scopes": [
"<string>"
]
}
]
}
],
"status": "active",
"created_by": {
"object": "user",
"type": "user",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"created_time": "2023-11-07T05:31:56Z",
"last_edited_time": "2023-11-07T05:31:56Z",
"last_run_time": "2023-11-07T05:31:56Z",
"last_run_at": "2023-11-07T05:31:56Z",
"instructions": "<string>"
}
],
"has_more": true,
"next_cursor": "<string>"
}{
"object": "error",
"message": "<string>",
"code": "invalid_json",
"status": 400,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "unauthorized",
"status": 401,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "restricted_resource",
"status": 403,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "object_not_found",
"status": 404,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "row_limit_exceeded",
"status": 406,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "conflict_error",
"status": 409,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "rate_limited",
"status": 429,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "internal_server_error",
"status": 500,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "service_unavailable",
"status": 503,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "gateway_timeout",
"status": 504,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "service_overload",
"status": 529,
"additional_data": {}
}List Agents
curl --request GET \
--url https://api.notion.com/v1/agents \
--header 'Authorization: Bearer <token>' \
--header 'Notion-Version: <notion-version>'import requests
url = "https://api.notion.com/v1/agents"
headers = {
"Notion-Version": "<notion-version>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'Notion-Version': '<notion-version>', Authorization: 'Bearer <token>'}
};
fetch('https://api.notion.com/v1/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.notion.com/v1/agents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Notion-Version: <notion-version>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.notion.com/v1/agents"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Notion-Version", "<notion-version>")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.notion.com/v1/agents")
.header("Notion-Version", "<notion-version>")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.notion.com/v1/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Notion-Version"] = '<notion-version>'
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"object": "list",
"type": "agent",
"results": [
{
"object": "agent",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent_type": "notion_ai",
"name": "<string>",
"description": "<string>",
"instructions_page_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"icon": {
"type": "emoji",
"emoji": "😀"
},
"version": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"number": 123,
"published_at": "<string>"
},
"agent_version": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"number": 123,
"published_at": "<string>"
},
"model": {
"mode": "auto"
},
"connections": [
{
"type": "notion",
"name": "<string>",
"account": null,
"permissions": [
{
"target": {
"type": "page",
"id": "<string>"
},
"scopes": [
"<string>"
]
}
]
}
],
"status": "active",
"created_by": {
"object": "user",
"type": "user",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"created_time": "2023-11-07T05:31:56Z",
"last_edited_time": "2023-11-07T05:31:56Z",
"last_run_time": "2023-11-07T05:31:56Z",
"last_run_at": "2023-11-07T05:31:56Z",
"instructions": "<string>"
}
],
"has_more": true,
"next_cursor": "<string>"
}{
"object": "error",
"message": "<string>",
"code": "invalid_json",
"status": 400,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "unauthorized",
"status": 401,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "restricted_resource",
"status": 403,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "object_not_found",
"status": 404,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "row_limit_exceeded",
"status": 406,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "conflict_error",
"status": 409,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "rate_limited",
"status": 429,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "internal_server_error",
"status": 500,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "service_unavailable",
"status": 503,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "gateway_timeout",
"status": 504,
"additional_data": {}
}{
"object": "error",
"message": "<string>",
"code": "service_overload",
"status": 529,
"additional_data": {}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
The API version to use for this request. The latest version is 2026-03-11.
2026-03-11 Query Parameters
Filter agents by name (case-insensitive substring match).
Filter agents by one or more agent types.
1 - 100 elementsOne of: notion_ai, custom_agent, autofill_custom_agent, external
notion_ai, custom_agent, autofill_custom_agent, external Filter agents by one or more agent IDs. Use notion_ai for Notion Agent (personal agent).
1 - 100 elementsFilter agents by one or more creator IDs. Use "me" for the user associated with the API token.
1 - 100 elementsIf 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.
The number of items from the full list desired in the response. Maximum: 100
1 <= x <= 100Whether to include inline instructions for each agent. Defaults to false.