List Agent Groups

POST /v2/agents/groups/list

List Agent Groups

cURL

curl --request POST \
  --url https://api.velt.dev/v2/agents/groups/list \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '{
  "data": {}
}'

{
  "result": {
    "status": "success",
    "message": "Agent groups fetched successfully",
    "data": {
      "groups": []
    }
  }
}

Use this API to list all agent groups in the workspace. Returns IAgentGroupSummary[] — the full agentIds array is intentionally stripped from each row and replaced with an agentCount field, so list payloads stay O(1) per group regardless of group size.

To fetch the complete agentIds array for a specific group, call Get Group.

Endpoint

POST https://api.velt.dev/v2/agents/groups/list

Headers

x-velt-api-key · string · required

Your API key.

x-velt-auth-token · string · required

Your Auth Token.

Body

Params

data · object · required

Empty object — only the apiKey (injected from headers) is required.

Example Requests

List all groups

{
  "data": {}
}

Response

Success Response

{
  "result": {
    "status": "success",
    "message": "Agent groups fetched successfully",
    "data": {
      "groups": [
        {
          "id": "grp_9f3ac2",
          "name": "Brand QA",
          "description": "All brand-quality agents",
          "agentCount": 12,
          "metadata": {
            "apiKey": "ak_xxx",
            "organizationId": "server_org_001",
            "documentId": "server_doc_001"
          },
          "createdAt": 1711900000000,
          "updatedAt": 1711900000000
        },
        {
          "id": "grp_a72bc1",
          "name": "Accessibility Suite",
          "agentCount": 4,
          "metadata": { "apiKey": "ak_xxx" },
          "createdAt": 1711800000000,
          "updatedAt": 1711800000000
        }
      ]
    }
  }
}

Field	Type	Description
data.groups	object[]	Array of group summary documents

Each summary contains id, name, description?, agentCount, metadata, createdAt, updatedAt. The full agentIds array is omitted; fetch it via Get Group.

Failure Response

{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}

{
  "result": {
    "status": "success",
    "message": "Agent groups fetched successfully",
    "data": {
      "groups": []
    }
  }
}