Manage Custom Agents with the Admin API

If you're an admin on the Enterprise Plan, you can manage the Custom Agents in your workspace with the Admin API. Instead of clicking through settings one agent at a time, your team can pull agent and usage info into your own tools and apply the same rules across many agents at once. The Admin API is available only to Enterprise org admins using an org-owned admin token.

• See every Custom Agent in your workspace. Get a list of all agents, including who created each one, whether it's active, which model it uses, when it last ran, and what it has access to.

• Track who has access to a Custom Agent. Update an agent’s sharing permissions.

• Track credit usage. See how many credits each agent has used, and track credit usage in bulk.

• Set credit limits. Set or change the credit limit for a single agent, or set a workspace default for all Custom Agents.

• Choose who can create agents. Set your workspace's agent creation policy, and pause all agents across the workspace if you need to.

• Turn an agent off or on. Stop a specific agent from running without deleting its setup, and turn it back on later.

• Delete an agent. Remove an agent from use. Its setup is kept so it can be recovered if needed.

• Your workspace must be on the Enterprise Plan.

• The Admin API uses organization-level admin access that your organization sets up, not personal integration tokens. For setup steps, see the developer documentation →

Everything the Admin API does has a matching control in Notion:

• The Agent Directory (Settings → Notion AI → Agents) shows and manages the agents in your workspace.

• The Notion credits dashboard shows agent credit usage.

• Creation controls set who can create agents.

Use Settings for one-off changes. Use the Admin API when you want to automate these tasks, manage many agents at once, or bring usage data into your own reporting tools.

• Pull credit usage into internal reports, so each team can see what its Custom Agents cost.

• Apply the same limits or rules to many agents at once.

• Transfer ownership for agents that should continue. Turn off or remove agents that are no longer needed.