---
title: "List Agents"
method: GET
path: "/api/mesh/{team_key}/agents"
tags: ["mesh"]
---

# List Agents

`GET /api/mesh/{team_key}/agents`

## Request

- Base URL: `https://api.superit.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.superit.ai/api/mesh/{team_key}/agents`
- Auth: HTTP bearer

Paginated agents for a team.

## Path parameters

- `team_key` string, required

## Query parameters

- `q` string
- `status` 'all' | 'online' | 'unstable' | 'offline'
- `platform` string[]
- `unverified` boolean
- `page` integer
- `pageSize` integer

## Response `200`

Successful Response

- PaginatedResponseAgent
  - `count` integer, required
  - `page` integer, required
  - `pageSize` integer, required
  - `totalPages` integer, required
  - `results` Agent[], required
    - `key` string, required
    - `hostname` string, required
    - `machineId` string, nullable
    - `deviceKey` string, nullable
    - `osPlatform` string, nullable
    - `version` string, nullable
    - `isOnline` boolean
    - `connection` DeviceConnection: A device's connection tier as the API reports it. ``since`` is the continuity anchor — when the current unbroken stretch began. ``last_contact`` is the last time either stream was heard from, which is what an offline device's tooltip counts from. Both are raw timestamps: the client renders the relative wording so it stays live in a long-open tab.
      - `tier` 'online' | 'unstable' | 'offline', required: How much the mesh trusts a device's reachability right now. Deliberately describes observed connection quality, not a tested prediction that a command will succeed — nothing here exercises the agent's command responder, so a claim of confidence would be unearned.
      - `reasonCode` 'steady' | 'recently_connected' | 'flapping' | 'stream_disagreement' | 'slowing' | 'unreachable' | 'never_seen', required: Why a device landed on its tier. Unstable collapses three different faults, so the badge shows the tier and the tooltip shows this.
      - `since` string, nullable
      - `lastContact` string, nullable
      - `recentGaps` integer
    - `lastSeen` string, nullable
    - `sessions` SessionSummary[]
      - `username` string, required
      - `isVerified` boolean, required

## Other responses

- `400`: Invalid input
- `401`: Not authenticated
- `403`: Forbidden
- `404`: Not found
- `405`: Method not allowed
- `409`: Conflict
- `422`: Validation Error

---

[API](https://skmtc.dev/superit/apis/super-it-api.md) - [All operations](https://skmtc.dev/superit/apis/super-it-api/llms.txt) - [OpenAPI document](https://skmtc.dev/superit/apis/super-it-api/revisions/4944d556c2bb?raw)