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": {}
}'

import requests

url = "https://api.velt.dev/v2/agents/groups/list"

payload = { "data": {} }
headers = {
    "x-velt-api-key": "<x-velt-api-key>",
    "x-velt-auth-token": "<x-velt-auth-token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-velt-api-key': '<x-velt-api-key>',
    'x-velt-auth-token': '<x-velt-auth-token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({data: {}})
};

fetch('https://api.velt.dev/v2/agents/groups/list', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.velt.dev/v2/agents/groups/list",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'data' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-velt-api-key: <x-velt-api-key>",
    "x-velt-auth-token: <x-velt-auth-token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.velt.dev/v2/agents/groups/list"

	payload := strings.NewReader("{\n  \"data\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
	req.Header.Add("x-velt-auth-token", "<x-velt-auth-token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.velt.dev/v2/agents/groups/list")
  .header("x-velt-api-key", "<x-velt-api-key>")
  .header("x-velt-auth-token", "<x-velt-auth-token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.velt.dev/v2/agents/groups/list")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "result": {
    "status": "success",
    "message": "Agent groups fetched successfully",
    "data": {
      "groups": [
        {
          "id": "grp_9f3ac2",
          "name": "Brand QA",
          "agentCount": 12,
          "metadata": { "apiKey": "ak_xxx" },
          "createdAt": 1711900000000,
          "updatedAt": 1711900000000
        }
      ]
    }
  }
}

Use this API to list all agent groups in the workspace. Each row is an IAgentGroupSummary — the full agentIds array is intentionally stripped and replaced with an agentCount (equal to agentIds.length) so list payloads stay O(1) per group. Clients that need the full membership list should call Get Group by id.

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

Show properties

The body carries no fields other than the injected apiKey. Send an empty data object.

Example Requests

{
  "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",
            "clientOrganizationId": "org_001",
            "clientDocumentId": "doc_001"
          },
          "createdAt": 1711900000000,
          "updatedAt": 1711900000000
        }
      ]
    }
  }
}

Field	Type	Description
groups[].id	string	Group id.
groups[].name	string	Group name.
groups[].description	string	Group description (if set).
groups[].agentCount	number	Number of member agents (replaces the full agentIds).
groups[].metadata	object	Stored metadata.
groups[].createdAt	number	Epoch ms creation timestamp.
groups[].updatedAt	number	Epoch ms last-updated timestamp.

{
  "result": {
    "status": "success",
    "message": "Agent groups fetched successfully",
    "data": {
      "groups": [
        {
          "id": "grp_9f3ac2",
          "name": "Brand QA",
          "agentCount": 12,
          "metadata": { "apiKey": "ak_xxx" },
          "createdAt": 1711900000000,
          "updatedAt": 1711900000000
        }
      ]
    }
  }
}