---
title: "Get agent insights"
method: GET
path: "/v1/agents/{agent_id}/insights"
tags: ["Agents"]
---

# Get agent insights

`GET /v1/agents/{agent_id}/insights`

## Path parameters

- `agent_id` union, required — The agent ID (a UUID), or `notion_ai` for the personal agent. Endpoint-specific restrictions still apply.
  - string
  - 'notion_ai' | '33333333-3333-3333-3333-333333333333' — One of: `notion_ai`, `33333333-3333-3333-3333-333333333333`

## 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.
- `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.

## Headers

- `Notion-Version` '2026-03-11', required

## Response `200`

- object
  - `object` 'agent_insights', required — Always `agent_insights`
  - `id` string, uuid, required
  - `name` string, required
  - `agent_type` 'custom_agent' | 'autofill_custom_agent', required — One of: `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' | 'failure_limit' | 'mark_session_failed_autopause' | 'disabled_from_workspace_settings' | '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`, `failure_limit`, `mark_session_failed_autopause`, `disabled_from_workspace_settings`, `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, nullable, required
    - `id` string, required
    - `type` 'user' | 'bot', required — One of: `user`, `bot`
  - `total_credits_used` number, required — Premium AI credits consumed by this agent within the window.
  - `credit_limit` union, required — Enforced per-agent credit limit; null when none is configured, and "hidden" when the caller lacks full access to the agent.
    - number
    - 'hidden' — Always `hidden`
  - `runs_completed` number, required — Number of runs recorded for this agent within the window.

## Other responses

- `400`
- `401`
- `403`
- `404`
- `406`
- `409`
- `429`
- `500`
- `503`
- `504`
- `529`

---

[API](https://skmtc.net/notion/apis/notion-api.md) · [All operations](https://skmtc.net/notion/apis/notion-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/notion/notion-api/revisions/dee5763763b0/schema)