List User Groups

This endpoint returns a page of user groups in your account.

Endpoint

GET /v1/user-groups/user-groups

Authentication

Include your API key in the x-api-key header. See Authentication.

Required Scope

user-groups:read

Query Parameters

Parameter	Type	Required	Description
page	number	No	Zero-based page index. Defaults to 0.
pageSize	number	No	Number of groups per page. Defaults to 25.
q	string	No	Search text matched against the group name and description.
sortCol	"name" | "createdAt" | "updatedAt"	No	Sort column. Applies only when sortDir is also sent.
sortDir	"asc" | "desc"	No	Sort direction. Applies only when sortCol is also sent.

When no valid sort is sent, groups are sorted by updatedAt and then createdAt, newest first. See Pagination for paging and sorting rules.

Request Body

This endpoint does not accept a request body.

Example Request

cURL

curl "https://api.crewsum.com/v1/user-groups/user-groups?page=0&pageSize=25" \
  -H "x-api-key: $CREWSUM_API_KEY"

JavaScript

const response = await fetch(
  "https://api.crewsum.com/v1/user-groups/user-groups?page=0&pageSize=25",
  {
    headers: {
      "x-api-key": process.env.CREWSUM_API_KEY,
    },
  },
);
const result = await response.json();

HTTP

GET /v1/user-groups/user-groups?page=0&pageSize=25 HTTP/1.1
Host: api.crewsum.com
x-api-key: <your-api-key>

Response

On success, the API returns HTTP 200 OK.

Example Response

{
  "message": "Successfully fetched user groups",
  "data": {
    "groups": [
      {
        "id": "36b735f8-4dd7-4c3c-836f-35d2fe84e872",
        "name": "Operations",
        "description": "Users who manage operations work.",
        "userCount": 3,
        "createdAt": "2026-05-27T18:00:00.000Z",
        "updatedAt": null
      }
    ],
    "count": 1
  }
}

Behavior

• count is the total number of groups that match q, not the number on this page.
• userCount is the number of users in each group.
• List items do not include members or assignments. Use Get User Group for those.

Error Responses

Status	Meaning
500	"Error fetching user groups": the request failed.

Authentication and scope failures are described in Errors.

Related Webhooks

This endpoint does not trigger a webhook.