Agents

Get agent insights

Changed on
get/v1/agents/{agent_id}/insights

Request

  • Base URL
    https://api.notion.com
  • URL
    https://api.notion.com/v1/agents/{agent_id}/insights
  • Auth
    HTTP bearer

Path parameters

string required
OR
'notion_ai' | '33333333-3333-3333-3333-333333333333' required

One of: notion_ai, 33333333-3333-3333-3333-333333333333

Query parameters

start_timeinteger

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.

end_timeinteger

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.

Headers

Notion-Version'2026-03-11' required

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

Response

object'agent_insights' required

Always agent_insights

namestring required
agent_type'notion_ai' | 'custom_agent' | 'autofill_custom_agent' required

One of: notion_ai, custom_agent, autofill_custom_agent

status'active' | 'disabled' | 'deleted' required

One of: active, disabled, deleted

pause_reason'run_limit' | 'credit_limit' | 'runaway_credit_usage' | 'workspace_credit_limit' | 'owner_allowance_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' nullable required

One of: run_limit, credit_limit, runaway_credit_usage, workspace_credit_limit, owner_allowance_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

total_credits_usednumber required

Premium AI credits consumed by this agent within the window.

runs_completednumber required

Number of runs recorded for this agent within the window.

Changes

  • 789bd1e5766bRevision changes
    • warning

      added the new owner_allowance_limit enum value to the / response property for the response status

  • 39fd52dfa388Revision changes
    • breaking

      added subschema #2 to the response property oneOf list for the response status

    • breaking

      the response's property type changed from string to no type, and format from uuid to no format for status

    • warning

      added the new disabled_from_workspace_settings_but_resumable enum value to the / response property for the response status

    • warning

      added the new notion_ai enum value to the response property for the response status