Get Agent Group

POST /v2/agents/groups/get

Get Agent Group

cURL

curl --request POST \
  --url https://api.velt.dev/v2/agents/groups/get \
  --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": {
    "groupId": "<string>"
  }
}
'

import requests

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

payload = { "data": { "groupId": "<string>" } }
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: {groupId: '<string>'}})
};

fetch('https://api.velt.dev/v2/agents/groups/get', 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/get",
  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' => [
        'groupId' => '<string>'
    ]
  ]),
  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/get"

	payload := strings.NewReader("{\n  \"data\": {\n    \"groupId\": \"<string>\"\n  }\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/get")
  .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    \"groupId\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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    \"groupId\": \"<string>\"\n  }\n}"

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

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

Use this API to fetch a single agent group by id. The response includes the full agentIds membership array. To list all groups without the full membership arrays, use the List Groups endpoint instead.

Endpoint

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

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

groupId · string · required

Min 1 char. Agent group id.

Example Requests

{
  "data": {
    "groupId": "grp_9f3ac2"
  }
}

Response

Success Response

{
  "result": {
    "status": "success",
    "message": "Agent group fetched successfully",
    "data": {
      "group": {
        "id": "grp_9f3ac2",
        "name": "Brand QA",
        "description": "All brand-quality agents",
        "agentIds": ["abc123def456", "spell-check"],
        "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
group.id	string	Group id.
group.name	string	Group name.
group.description	string	Group description (if set).
group.agentIds	string[]	Full member agent id list.
group.metadata	object	Stored metadata.
group.createdAt	number	Epoch ms creation timestamp.
group.updatedAt	number	Epoch ms last-updated timestamp.

Failure Response

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

Errors: NOT_FOUND if the group does not exist.

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