> ## Documentation Index > Fetch the complete documentation index at: https://developers.notion.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve agent insights > Retrieve configuration and usage insights for a Custom Agent. ## OpenAPI ````yaml get /v1/agents/{agent_id}/insights openapi: 3.1.0 info: title: Notion API version: 1.0.0 termsOfService: >- https://notion.notion.site/Terms-and-Privacy-28ffdd083dc3473e9c2da6ec011b58ac servers: - url: https://api.notion.com security: - bearerAuth: [] tags: - name: Databases description: Database endpoints - name: Data sources description: Data source endpoints - name: Pages description: Page endpoints - name: Async tasks description: Async task endpoints - name: Blocks description: Block endpoints - name: Comments description: Comment endpoints - name: File uploads description: File upload endpoints - name: OAuth description: OAuth endpoints (basic authentication) - name: Users description: User endpoints - name: Search description: Search endpoints - name: Views description: View endpoints - name: Agents description: Agent endpoints - name: Sessions description: Session endpoints - name: Custom emojis description: Custom emoji endpoints - name: Meeting notes description: Meeting notes endpoints paths: /v1/agents/{agent_id}/insights: get: tags: - Agents summary: Get agent insights operationId: get-agent-insights parameters: - name: agent_id in: path required: true schema: oneOf: - $ref: '#/components/schemas/idRequest' - type: string enum: - notion_ai - 33333333-3333-3333-3333-333333333333 description: 'One of: `notion_ai`, `33333333-3333-3333-3333-333333333333`' description: >- The agent ID (a UUID), or `notion_ai` for the personal agent. Endpoint-specific restrictions still apply. - name: start_time in: query schema: type: integer minimum: 0 description: >- 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. - name: end_time in: query schema: type: integer minimum: 0 description: >- 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. - $ref: '#/components/parameters/notionVersion' responses: '200': description: '' content: application/json: schema: type: object properties: object: type: string const: agent_insights description: Always `agent_insights` id: $ref: '#/components/schemas/idResponse' name: type: string agent_type: type: string enum: - custom_agent - autofill_custom_agent description: 'One of: `custom_agent`, `autofill_custom_agent`' status: type: string enum: - active - disabled - deleted description: 'One of: `active`, `disabled`, `deleted`' pause_reason: oneOf: - type: string enum: - 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 description: >- 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` - type: 'null' created_by: oneOf: - type: object properties: id: type: string type: type: string enum: - user - bot description: 'One of: `user`, `bot`' additionalProperties: false required: - id - type - type: 'null' total_credits_used: type: number description: >- Premium AI credits consumed by this agent within the window. credit_limit: oneOf: - type: number - type: string const: hidden description: Always `hidden` - type: 'null' description: >- Enforced per-agent credit limit; null when none is configured, and "hidden" when the caller lacks full access to the agent. runs_completed: type: number description: Number of runs recorded for this agent within the window. additionalProperties: false required: - object - id - name - agent_type - status - pause_reason - created_by - total_credits_used - credit_limit - runs_completed '400': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_400' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_401' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_403' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_404' '406': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_406' '409': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_409' '429': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_429' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_500' '503': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_503' '504': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_504' '529': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_529' x-codeSamples: - lang: javascript label: TypeScript SDK source: |- 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" }) components: schemas: idRequest: type: string idResponse: type: string format: uuid error_api_400: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - invalid_json - invalid_request_url - invalid_request - missing_version - invalid_beta - validation_error - invalid_credit_limit status: const: 400 required: - code - status additionalProperties: false error_api_401: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - unauthorized status: const: 401 required: - code - status additionalProperties: false error_api_403: oneOf: - allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - restricted_resource - status_change_not_allowed status: const: 403 required: - code - status additionalProperties: false - allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: const: workspace_credits_exhausted status: const: 403 additional_data: type: object properties: tool_error_code: const: workspace_credits_exhausted tool_error_class: const: entitlement_required tool_error_retryable: const: 'false' recovery_kind: enum: - contact_workspace_owner - open_workspace_credit_settings description: The recovery action selected by Notion for the caller. recovery_url: type: string format: uri description: >- Present when recovery_kind directs the caller to a settings page. required: - tool_error_code - tool_error_class - tool_error_retryable - recovery_kind additionalProperties: oneOf: - type: string - type: array items: type: string required: - code - status - additional_data - allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: const: agent_credit_limit_reached status: const: 403 additional_data: type: object properties: tool_error_code: const: agent_credit_limit_reached tool_error_class: const: entitlement_required tool_error_retryable: const: 'false' recovery_kind: enum: - contact_workspace_owner - none - open_agent_settings - request_agent_limit_increase - request_pending description: The recovery action selected by Notion for the caller. recovery_url: type: string format: uri description: >- Present when recovery_kind directs the caller to a settings page. required: - tool_error_code - tool_error_class - tool_error_retryable - recovery_kind additionalProperties: oneOf: - type: string - type: array items: type: string required: - code - status - additional_data error_api_404: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - object_not_found - directory_not_found status: const: 404 required: - code - status additionalProperties: false error_api_406: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - row_limit_exceeded status: const: 406 required: - code - status additionalProperties: false error_api_409: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - conflict_error - idempotency_key_reused - agent_deleted status: const: 409 required: - code - status additionalProperties: false error_api_429: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - rate_limited status: const: 429 required: - code - status additionalProperties: false error_api_500: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - internal_server_error status: const: 500 required: - code - status additionalProperties: false error_api_503: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - service_unavailable status: const: 503 required: - code - status additionalProperties: false error_api_504: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - gateway_timeout status: const: 504 required: - code - status additionalProperties: false error_api_529: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - service_overload status: const: 529 required: - code - status additionalProperties: false publicApiCommonErrorResponse: type: object properties: object: const: error message: type: string additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string required: - object - message parameters: notionVersion: name: Notion-Version in: header required: true schema: enum: - '2026-03-11' description: >- The [API version](/reference/versioning) to use for this request. The latest version is `2026-03-11`. securitySchemes: bearerAuth: type: http scheme: bearer ````