Get All User Groups

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

HTTP Request

GET/api/users/groups

Authorization

Authorization

• Required: Yes
• Permission: Staff or Admin
• 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 filter results by `name` and `notes`
ordering	String	—	Field to order results by (`id`, `name`, `_users_count`, `created_at`, `updated_at`). Prefix with '-' for descending order
min_users	Integer	—	Minimum number of users in the group
max_users	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 last update date
created_from	String (YYYY-MM-DD)	—	Start date for groups created after this date
updated_from	String (YYYY-MM-DD)	—	Start date for groups updated after this date
created_to	String (YYYY-MM-DD)	—	End date for groups created before this date
updated_to	String (YYYY-MM-DD)	—	End date for groups updated before this 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"

Status Codes

Code	Description
200	User groups retrieved successfully
400	Bad request — invalid parameters
401	Unauthorized — authentication required
403	Forbidden — insufficient permissions
500	Internal server error

Response Fields

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"
    }
  ]
}