Retrieve agent insights

Retrieve configuration and usage insights for a Custom Agent or the authenticated user’s personal agent.

GET /v1/agents/{agent_id}/insights

TypeScript SDK

JavaScript

import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.agents.retrieveInsights({
  agent_id: "1f0c7c06-781b-4987-9986-5c8dd3028013"
})

200

{
  "object": "agent_insights",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "agent_type": "notion_ai",
  "status": "active",
  "pause_reason": "run_limit",
  "created_by": {
    "id": "<string>",
    "type": "user"
  },
  "total_credits_used": 123,
  "credit_limit": 123,
  "runs_completed": 123
}

Personal agent insights

Pass notion_ai as the agent_id to read insights for the personal agent (Notion AI) instead of a Custom Agent. The response keeps the same agent_insights shape, with a few differences:

• id and agent_type are both notion_ai.
• created_by is the user the token acts as.
• status is always active and pause_reason is always null, because the personal agent has no per-agent status controls.
• credit_limit reports the workspace’s default per-member credit limit, or null when the workspace has not set one.

Access

Only a personal access token can read personal agent insights, and the totals always cover the user that token acts as — never another member’s usage. Any other token receives a 404 object_not_found.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Notion-Version · enum<string> · required

The API version to use for this request. The latest version is 2026-03-11.

Available options: 2026-03-11

Path Parameters

agent_id · string enum<string> · required

The agent ID (a UUID), or notion_ai for the personal agent. Endpoint-specific restrictions still apply.

Query Parameters

start_time · integer

Start of the insights window, as an epoch timestamp in seconds. Must be supplied together with end_time; if either is omitted the window defaults to the current billing period.

Required range: x >= 0

end_time · integer

End of the insights window, as an epoch timestamp in seconds. Must be supplied together with start_time; if either is omitted the window defaults to the current billing period.

Required range: x >= 0

Response

200

application/json

object · string · required

Always agent_insights

Allowed value: "agent_insights"

id · string<uuid> string · required

name · string · required

agent_type · enum<string> · required

One of: notion_ai, custom_agent, autofill_custom_agent

Available options: notion_ai, custom_agent, autofill_custom_agent

status · enum<string> · required

One of: active, disabled, deleted

Available options: active, disabled, deleted

pause_reason · enum<string> | null · required

One of: run_limit, credit_limit, runaway_credit_usage, workspace_credit_limit, failure_limit, mark_session_failed_autopause, disabled_from_workspace_settings, disabled_from_workspace_settings_but_resumable, disabled_from_api, disabled_from_agent_settings, disabled_due_to_no_members_with_access, disabled_due_to_lack_of_editors, disabled_by_notion, internal_error, needs_user_review, tool_unavailable

Available options: run_limit, credit_limit, runaway_credit_usage, workspace_credit_limit, failure_limit, mark_session_failed_autopause, disabled_from_workspace_settings, disabled_from_workspace_settings_but_resumable, disabled_from_api, disabled_from_agent_settings, disabled_due_to_no_members_with_access, disabled_due_to_lack_of_editors, disabled_by_notion, internal_error, needs_user_review, tool_unavailable

created_by · object | null · required

Show child attributes

total_credits_used · number · required

Premium AI credits consumed by this agent within the window.

credit_limit · number string · required

Enforced per-agent credit limit; null when none is configured, and "hidden" when the caller lacks full access to the agent.

runs_completed · number · required

Number of runs recorded for this agent within the window.