List agents

Returns a paginated list of agents in your organization, newest first. Soft-deleted agents are excluded by default; restore them from the dashboard trash if you need them back.

Scope: agents:read

Query parameters

Example request

curl 'https://dashboard.getmacha.com/api/v1/agents?limit=10' \
  -H "Authorization: Bearer $MACHA_API_KEY"

Example response

{
  "data": [
    {
      "id": "agent_64f1c0ef2ec711ef6dc1dcf",
      "handle": "ticketTriage",
      "name": "Triage",
      "model": "gpt-5.4",
      "is_active": true,
      "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_a0b88aa084bac0f7",
    "next_cursor": "agent_64f1c0ef2ec711ef6dc1dcd"
  }
}

Walking the full list

async function listAllAgents() {
  const all = [];
  let cursor = null;
  while (true) {
    const params = new URLSearchParams({ limit: '100' });
    if (cursor) params.set('cursor', cursor);
    const res = await fetch(
      `https://dashboard.getmacha.com/api/v1/agents?${params}`,
      { headers: { Authorization: `Bearer ${process.env.MACHA_API_KEY}` } },
    );
    const body = await res.json();
    all.push(...body.data);
    if (!body.meta.next_cursor) break;
    cursor = body.meta.next_cursor;
  }
  return all;
}

Errors