Skip to content
AiKYNETIX

List the team's client groups

GET
/api/client-groups/
curl --request GET \
  --url http://localhost:8000/api/client-groups/ \
  --header 'Authorization: Bearer <token>'

Every ClientGroup owned by the active team, sorted by name. Each carries its member_ids (the roster) + member_count, whether it carries target ranges of its own (has_ranges, #2518) and its ranges_priority — sort by (ranges_priority, created_at, id) for the order those ranges take precedence in. Team-scoped.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer

Number of results to return per page.

offset
integer

The initial index from which to return the results.

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
count
required
integer
next
string format: uri
nullable
previous
string format: uri
nullable
results
required
Array<object>

A team-scoped client group (#545). name / description / colour are writable on create + PATCH; the roster (member_ids) is read-only here — mutate it via the /members/ endpoints. member_count powers the board column header without a second round-trip.

object
id
required
string format: uuid
name
required

Group name. Required; unique within the team.

string
<= 120 characters
description

Optional free-text description of the group.

string
<= 500 characters
colour

Optional UI tint — a design-token key (e.g. tone-recovery) or empty. Cosmetic; the board falls back to a deterministic colour.

string
<= 32 characters
member_ids
required

UUIDs of the clients in this group (many-to-many).

Array<string>
member_count
required

Number of clients in the group.

integer
has_ranges
required

Whether the group carries any target range of its own (#2518) — a MetricThreshold row with client_group = this group. Edit them in /api/thresholds/?client_group=<id>.

boolean
ranges_priority
required

Precedence of this group’s own target ranges (#2518) for a client in several groups: per metric, the group first in (ranges_priority, created_at, id) order wins — LOWER wins. Not unique (ties fall back to creation order). Read-only here; set it with POST /api/client-groups/ranges-priority/. A new group starts at the bottom.

integer
created_at
required
string format: date-time
updated_at
required
string format: date-time

Examples

ExampleSprintSquad

Sprint squad

{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "b3f1c0a2-0000-4000-8000-000000000001",
      "name": "Sprint squad",
      "description": "100–400 m specialists",
      "colour": "tone-recovery",
      "member_ids": [
        "a1f1c0a2-0000-4000-8000-0000000000aa"
      ],
      "member_count": 1,
      "has_ranges": true,
      "ranges_priority": 0,
      "created_at": "2026-06-10T12:00:00Z",
      "updated_at": "2026-06-10T12:00:00Z"
    }
  ]
}

401

Section titled “401”
Media typeapplication/json
object
detail
required

Human-readable message, or a stable machine code for the cases a client branches on. The standard envelope for 400 (validation — a field-keyed object may appear instead), 401 (missing / invalid credentials), 403 (authenticated but not permitted), and 404 (absent — cross-team records are collapsed to 404 so the API never leaks the existence of another team’s data).

string

Example generated

{
  "detail": "example"
}