Retrieve an agent

Fetch a single agent by ID.

GET /api/v1/agents/:id

Fetch a single agent by ID. Soft-deleted agents return 404 agent_not_found, if you need to read trashed agents, restore them from the dashboard first.

Scope: agents:read

Path parameters

Param	Type	Notes
`:id`	string	Agent identifier. Accepts the prefixed form (`agent_64f1c0ef2ec711ef6dc1dcf`) or a bare 24-character ObjectId.

Example request

curl https://dashboard.getmacha.com/api/v1/agents/agent_64f1c0ef2ec711ef6dc1dcf \
  -H "Authorization: Bearer $MACHA_API_KEY"

Example response

{
  "data": {
    "id": "agent_64f1c0ef2ec711ef6dc1dcf",
    "handle": "ticketTriage",
    "name": "Triage",
    "description": "Routes incoming Zendesk tickets to the right downstream agent.",
    "model": "gpt-5.4",
    "is_active": true,
    "color": "#000000",
    "avatar": "🚦",
    "tools_count": 2,
    "sub_agents_count": 4,
    "created_at": "2026-06-10T04:07:44.871Z",
    "updated_at": "2026-06-17T07:29:29.408Z"
  },
  "meta": { "request_id": "req_..." }
}

Errors

Status	Code	When
`401`	`unauthorized`	Missing, invalid, or revoked API key.
`403`	`insufficient_scope`	Key lacks `agents:read`.
`404`	`agent_not_found`	Unknown ID, soft-deleted past trash window, or belongs to another org.
`429`	`rate_limited`	Per-key rate ceiling exceeded.

📘

Bare ObjectIds work too

If you have raw Mongo IDs lying around from older integrations, pass them directly, /agents/64f1c0ef2ec711ef6dc1dcf resolves the same as /agents/agent_64f1c0ef2ec711ef6dc1dcf. Responses always use the prefixed form.