# List agent URL: https://docs.hanzo.ai/docs/openapi/agent/get-agent > Returns every agent defined in the caller's org, each with the number of runs recorded against it. `GET /v1/agent` > [Agent →](https://docs.hanzo.ai/docs/openapi/agent) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | -------------------------------------- | | **Address** | `https://api.hanzo.ai/v1/agent` | | **Method** | `GET` | | **Operation** | `get_agent` | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | Returns every agent defined in the caller's org, each with the number of runs recorded against it. ## Request `GET /v1/agent` takes no parameters and no body — the credential is the whole request. ## Response | Status | Body | Meaning | | --------- | --------------- | ------- | | `200` | agent.agentList | ok | | `default` | problem-details | refused | `200` body — 22 fields. | Field | In | Type | Always | Description | | ----------------------------- | ---- | ------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agents` | body | agent.agentView\[] | — | Agents is the org's agents, each carrying its recorded run count. | | `agents[].avatar` | body | string | — | Avatar is an image the agent is drawn as — a link to one, or the bytes inline as a data URL, up to 96 KiB. | | `agents[].cap_micro_usd` | body | integer (int64) | — | CapMicroUSD is the total this agent may spend within one Period, as an integer number of micro-USD (1,000,000 = $1). | | `agents[].computeRef` | body | string | — | ComputeRef is the visor machine this bot is bound to, opaque here: this package stores and echoes it, and the binding's lifecycle belongs elsewhere. | | `agents[].consumed_micro_usd` | body | integer (int64) | — | ConsumedMicroUSD is what has been spent in the current period, in micro-USD. | | `agents[].createdAt` | body | string | — | CreatedAt is when the agent was defined, RFC 3339 in UTC to the second. | | `agents[].description` | body | string | — | Description is the one line another agent reads when deciding whether to call this one: the tool catalogue publishes it as the description of `agent_<name>`, falling back to "agent \" when it is empty. | | `agents[].emoji` | body | string | — | Emoji is the single glyph a caller picked when they had no image. | | `agents[].executionMode` | body | string | — | ExecutionMode is one-shot or long-running, and it decides who may start this agent. | | `agents[].id` | body | string | — | ID is the agent's stable handle, minted here as "agent\_" + 32 hex characters of crypto/rand. | | `agents[].lineage` | body | string\[] | — | Lineage is every agent above this one, nearest first — the parent, its parent, and so on to the agent a person defined. | | `agents[].max_task_micro_usd` | body | integer (int64) | — | MaxTaskMicroUSD is the ceiling for a single run, in micro-USD. | | `agents[].model` | body | string | — | Model is the Zen model this agent runs on, and it is always OUR name for it: writes normalize through cloud.ZenModel and the read normalizes again, so an upstream family name never leaves here even from a row written before that rule existed. | | `agents[].name` | body | string | — | Name is the agent's org-unique handle, matching ^\[A-Za-z0-9]\[A-Za-z0-9.\_-]{0,63}$. | | `agents[].parent` | body | string | — | Parent is the agent that spawned this one; absent for an agent a person defined. | | `agents[].period` | body | string | — | Period is the window the cap resets on: day, week or month. | | `agents[].runs` | body | integer (int64) | — | Runs is how many executions the org has recorded against this agent, counted at read time. | | `agents[].schedule` | body | string | — | Schedule is the 5-field cron the scheduler fires a long-running agent on, evaluated once a minute. | | `agents[].serviceAccountId` | body | string | — | ServiceAccountID is the IAM agent service account (\-\) a scheduled run is billed AS. | | `agents[].status` | body | string | — | Status is the agent's readiness, and today it is "ready" on every row: an agent is a definition rather than a provisioned thing, so nothing transitions it. | | `agents[].tools` | body | string\[] | — | Tools are the tool names this agent may call, and the list IS the authority: an agent that declares none gets none. | | `agents[].updatedAt` | body | string | — | UpdatedAt is the last time any field above was written, same format. | Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** ```bash hanzo agent list ``` **SDK** **.ts** ```ts import { Configuration, AgentApi } from 'hanzoai'; const api = new AgentApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.getAgent(); ``` **.py** ```python from hanzoai.cloud import ApiClient, Configuration from hanzoai.cloud.api import AgentApi client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"])) result = AgentApi(client).get_agent() ``` **.go** ```go cfg := hanzoai.NewConfiguration() cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY")) client := hanzoai.NewAPIClient(cfg) resp, _, err := client.AgentAPI.GetAgent(context.Background()).Execute() if err != nil { return err } ``` **.rs** ```rust use hanzo_client::apis::{configuration::Configuration, agent_api}; let mut cfg = Configuration::new(); cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok(); let result = agent_api::get_agent(&cfg, Default::default()).await?; ``` **.java** ```java import ai.hanzo.cloud.ApiClient; import ai.hanzo.cloud.api.AgentApi; ApiClient client = new ApiClient(); client.setBearerToken(System.getenv("HANZO_API_KEY")); var result = new AgentApi(client).getAgent(); ``` **HTTP** ```bash curl https://api.hanzo.ai/v1/agent \ -H "Authorization: Bearer $HANZO_API_KEY" ``` **MCP** MCP reaches **agent** through the `agent` tool, which names its 38 operations with its own verbs — this one among them, under a name only MCP declares. `describe` explains any of them: ```bash curl -X POST https://api.hanzo.ai/v1/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "describe", "arguments": { "op": "list_agents" } } }' ``` --- [Agent API](https://docs.hanzo.ai/docs/openapi/agent) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)