How do I list every agent my organization runs?
In agent.ceo, every agent is a role your organization holds, not a person's account. To list them, create
an API key that can only read agents. Then call GET /api/v1/customers/ORG/agents with it. The response
is your organization's registered agents.
Most organizations cannot do this step at all. IBM's Institute for Business Value found that 18% of organizations maintain a current and complete AI inventory. You cannot govern what you cannot list.
The calls, in order
| # | Where | What you do | What you get |
|---|---|---|---|
| 1 | API Keys | Create an organization key with only the read:agents scope | A key value to store |
| 2 | GET /api/v1/customers/ORG/agents | Call it with that key | 200 and your org's registered agents |
| 3 | API Keys | Confirm the key appears in your key list | Listed without its value |
| 4 | Your inventory | Record owner and purpose per agent | The part no API can answer for you |
1. A key that can only read agents
Create the key with a single scope, read:agents. Give it a name that says what it is for,
such as inventory-report. Store the value in your secret store, not in a script. The
API keys docs cover creating and revoking keys.
2. List the agents
curl -s "https://api.agent.ceo/api/v1/customers/$ORG/agents" \
-H "X-API-Key: $INVENTORY_KEY"
# expect 200 and your organization's agents
Then run the same check with inputs that must fail, so you know the check can fail:
# INVENTED_KEY: a string you made up, never issued by agent.ceo
curl -s -o /dev/null -w "%{http_code}\n" \
"https://api.agent.ceo/api/v1/customers/$ORG/agents" \
-H "X-API-Key: $INVENTED_KEY"
# expect a 4xx refusal, never 200
If a made-up key also returns 200, your check measures nothing. Stop and find out why before you trust the list.
3. From a list to an inventory
A list answers "what exists". An inventory answers "what exists, who owns it, and what may it touch". The Agent Registry docs describe the registry as the starting point for that inventory. The rest of the record is yours to keep.
| Field | Where it comes from |
|---|---|
| Agent and its role | The list call above |
| Owner (a named person or team) | You. Record it per agent |
| Purpose (one sentence) | You |
| Keys it depends on | The API Keys page lists keys by name and scope |
| Loops it runs | Your organization's loop list |
| Last reviewed | You. A date, not "ongoing" |
Rendering diagram…
A predefined role is one of the 16 that agent.ceo ships, and a custom role is one your organization defined with its own system prompt. Both kinds are roles your organization holds, so the list covers both.
Run it on a schedule
The list is only useful if it is current. Run the call on a schedule and compare it with the last run. Any agent that appears without an owner in your inventory is the one to ask about first. What each field should hold is covered in what should an AI agent inventory record?
FAQ
How do I list every agent my organization runs in agent.ceo?
Create an organization API key scoped only to reading agents, then call GET /api/v1/customers/ORG/agents with that key. The response lists your organization's registered agents. Because the key can only read agents, it is safe to hand to a reporting job.
Why use a separate API key just to list agents?
So the job that builds your inventory cannot change anything. A key scoped to reading agents can list them and nothing else, and you can revoke it without affecting any other integration. If the key leaks, the damage is a list, not a change.
Is a list of agents a complete AI agent inventory?
No. The list tells you what exists. An inventory also needs each agent's owner, what it is for, which keys and loops it holds, and when that was last reviewed. Start from the list, then record the rest for each agent.
Related: How to give an integration a scoped API key · Agent governance and inventory · Agent catalog