List all user groups

Retrieve a list of user groups with optional filtering, searching, and pagination.

HTTP Request

GET/api/users/groups/

NOTE: NOT USING THE TRAILING SLASH AT THE END OF THE URL RESULTS TO AN EXTRA REDIRECT WITH 301 STATUS

Authorization

Authorization

• Required: Yes
• Permission: Staff with GroupPermission or Admin
• Permission Code: 1202
• Authentication: Token-based (Authorization: Token <your_api_key>)

Query Parameters

Parameter	Type	Default	Description
limit	Integer	—	Number of results to return per page (default is 10)
offset	Integer	—	Number of results to skip before returning results (default is 0)
search	String	—	Search term to lookup results by`name` and `notes`
ordering	String	—	Order results by (`id`, `name`, `_users_count`, `created_at`, `updated_at`). Prefix with '-' for descending order
users_count_min	Integer	—	Minimum number of users in the group
users_count_max	Integer	—	Maximum number of users in the group
id_min	Integer	—	Minimum ID of the user group
id_max	Integer	—	Maximum ID of the user group
created_date	String (YYYY-MM-DD)	—	Exact creation date
updated_date	String (YYYY-MM-DD)	—	Exact updated date
created_from	String (YYYY-MM-DD)	—	Groups created after a specific date
updated_from	String (YYYY-MM-DD)	—	Groups last updated after a specific date
created_to	String (YYYY-MM-DD)	—	Groups created before a specific date
updated_to	String (YYYY-MM-DD)	—	Groups last updated before a specific date

Example Requests

🐍 Python

1import requests
2
3api = requests.Session()
4api.headers.update({'Authorization': 'Token XXXXXXXXXXXXXXXXXXXXXX'})
5response = api.get('http://www.example.com/api/users/groups/', params={
6  'limit': 5,
7  'ordering': 'name'
8})
9print(response.json())

🌐 Curl

1curl "http://www.example.com/api/users/groups/?limit=5&ordering=name" -H "Authorization: Token XXXXXXXXXXXXXXXXXXXXXX"

Response Fields

Field	Type	Description
count	Integer	Total number of categories
next	String	URL for the next page of results
previous	String	URL for the previous page of results
results	Array[Object]	Array of Group objects

Group Object Structure

Field	Type	Description
id	Integer	Unique identifier for the user group
name	String	Name of the user group
notes	String or null	Optional notes about the user group
users_count	Integer	Number of users in the group
created_at	String (ISO 8601)	Timestamp when the group was created
updated_at	String (ISO 8601)	Timestamp when the group was last updated

Example Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Admins",
      "notes": "Group for system administrators",
      "users_count": 5,
      "created_at": "2023-01-15T10:00:00Z",
      "updated_at": "2023-06-01T12:00:00Z"
    },
    {
      "id": 2,
      "name": "Editors",
      "notes": null,
      "users_count": 12,
      "created_at": "2023-02-20T14:30:00Z",
      "updated_at": "2023-05-25T09:15:00Z"
    }
  ]
}