> For the complete documentation index, see [llms.txt](https://docs.channex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.channex.io/api-v.1-documentation/groups-collection/get-list-of-groups-api.md).

# Get list of Groups API

## List groups

> List groups. Results are paginated; the \`meta\` block carries the page, limit, total and ordering.

```json
{"openapi":"3.1.0","info":{"title":"Channex.io — Public API","version":"0.0.0"},"tags":[{"name":"Groups","description":"Manage Groups — sets of Properties you manage together, and the users who may reach them. Every Property belongs to at least one Group and may belong to several; a Group that still holds a Property cannot be deleted."}],"servers":[{"url":"https://app.channex.io/api/v1","description":"Production server","variables":{}},{"url":"https://staging.channex.io/api/v1","description":"Staging server","variables":{}}],"security":[{"UserApiKeyAuth":[]}],"components":{"securitySchemes":{"UserApiKeyAuth":{"type":"apiKey","in":"header","name":"user-api-key","description":"API key for programmatic access, sent in the `user-api-key` header."}},"parameters":{"Groups.GroupListParams.title":{"name":"filter[title]","in":"query","required":false,"description":"Return only groups with exactly this title.","schema":{"type":"string"},"explode":false},"Common.Pagination.PaginationParams.page":{"name":"pagination[page]","in":"query","required":false,"description":"Page to return, counted from 1.","schema":{"$ref":"#/components/schemas/Common.Scalars.positiveInt"},"explode":false},"Common.Pagination.PaginationParams.limit":{"name":"pagination[limit]","in":"query","required":false,"description":"Number of items per page. Maximum is 100.","schema":{"$ref":"#/components/schemas/Common.Scalars.positiveInt","maximum":100},"explode":false},"Groups.GroupListParams.orderTitle":{"name":"order[title]","in":"query","required":false,"description":"Order groups by title.","schema":{"$ref":"#/components/schemas/Common.Pagination.OrderDirection"},"explode":false}},"schemas":{"Common.Scalars.positiveInt":{"type":"integer","format":"int32","minimum":1},"Common.Pagination.OrderDirection":{"type":"string","enum":["asc","desc"],"description":"Sort direction for list results."},"Groups.GroupResource":{"type":"object","required":["type","id","attributes","relationships"],"properties":{"type":{"type":"string","enum":["group"]},"id":{"$ref":"#/components/schemas/Common.Scalars.id"},"attributes":{"$ref":"#/components/schemas/Groups.Group"},"relationships":{"$ref":"#/components/schemas/Groups.GroupRelationships"}},"description":"A group as returned in responses."},"Common.Scalars.id":{"type":"string","format":"uuid"},"Groups.Group":{"type":"object","required":["id","title"],"properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}],"description":"Unique group identifier."},"title":{"type":"string","minLength":1,"maxLength":255,"description":"Group title."}},"description":"A group — a set of properties and the users who may reach them — as returned in responses."},"Groups.GroupRelationships":{"type":"object","required":["properties","users"],"properties":{"properties":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Groups.EmbeddedProperty"}}},"required":["data"],"description":"Properties in the group."},"users":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Authentication.EmbeddedUser"}}},"required":["data"],"description":"Users with access to the group."}},"description":"Relationships of a group resource: the properties it holds and the users who may reach them."},"Groups.EmbeddedProperty":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"$ref":"#/components/schemas/Common.Scalars.id"},"type":{"type":"string","enum":["property"]},"attributes":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/Common.Scalars.id"},"title":{"type":"string"}},"required":["id","title"]}},"description":"A property as it appears among a group's relationships."},"Authentication.EmbeddedUser":{"type":"object","required":["type","id","attributes"],"properties":{"type":{"type":"string","enum":["user"]},"id":{"$ref":"#/components/schemas/Common.Scalars.id"},"attributes":{"$ref":"#/components/schemas/Authentication.EmbeddedUserAttributes"}},"description":"A user embedded in another resource's relationships, carrying identifier, name and email."},"Authentication.EmbeddedUserAttributes":{"type":"object","required":["id","name","email"],"properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}],"description":"User identifier. Mirrors the resource id."},"name":{"type":"string","description":"Display name of the user."},"email":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.email"}],"description":"Email address the account is registered with."}},"description":"Identifier, display name and email address of an embedded user."},"Common.Scalars.email":{"type":"string","format":"email"},"Common.Pagination.PaginationMeta":{"type":"object","required":["page","limit","total","order_by","order_direction"],"properties":{"page":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.positiveInt"}],"description":"Page returned, counted from 1."},"limit":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.positiveInt"}],"maximum":100,"description":"Number of items per page. At most 100 — requests with `pagination[limit]` above 100 are rejected with `422 Unprocessable Entity`."},"total":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.nonNegativeInt"}]},"order_by":{"type":"string","description":"Field the results are ordered by."},"order_direction":{"allOf":[{"$ref":"#/components/schemas/Common.Pagination.OrderDirection"}],"description":"Direction the results are ordered in."}},"description":"Pagination and ordering metadata attached to list responses."},"Common.Scalars.nonNegativeInt":{"type":"integer","format":"int32","minimum":0},"Common.Errors.Unauthorized":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"title":{"type":"string","enum":["Unauthorized"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"Authentication credentials are missing or invalid."},"Common.Errors.InvalidArguments":{"type":"object","required":["errors"],"properties":{"errors":{"$ref":"#/components/schemas/Common.Errors.InvalidArgumentsObject"}},"description":"The request has missing or invalid arguments; `details` lists the messages per argument."},"Common.Errors.InvalidArgumentsObject":{"type":"object","required":["code","title","details"],"properties":{"code":{"type":"string","enum":["bad_request"]},"title":{"type":"string","enum":["Bad Request"]},"details":{"type":"object","unevaluatedProperties":{"type":"array","items":{"type":"string"}},"description":"Maps each invalid argument to the list of validation messages for that argument."}},"description":"Error object for invalid request arguments, adding per-argument messages."},"Common.Errors.InvalidNestedArguments":{"type":"object","required":["errors"],"properties":{"errors":{"$ref":"#/components/schemas/Common.Errors.InvalidNestedArgumentsObject"}},"description":"The request has invalid arguments; `details` lists the messages per argument, one level deeper for an argument that is itself a group."},"Common.Errors.InvalidNestedArgumentsObject":{"type":"object","required":["code","title","details"],"properties":{"code":{"type":"string","enum":["bad_request"]},"title":{"type":"string","enum":["Bad Request"]},"details":{"type":"object","unevaluatedProperties":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"object","unevaluatedProperties":{"type":"array","items":{"type":"string"}}}]},"description":"Maps each invalid argument to its validation messages: a list of messages for a flat argument, and the messages per argument inside the group for a nested one."}},"description":"Error object for invalid request arguments, adding per-argument messages and, for an argument that is a group, the messages inside it."}}},"paths":{"/groups":{"get":{"operationId":"Groups_list","summary":"List groups","description":"List groups. Results are paginated; the `meta` block carries the page, limit, total and ordering.","parameters":[{"$ref":"#/components/parameters/Groups.GroupListParams.title"},{"$ref":"#/components/parameters/Common.Pagination.PaginationParams.page"},{"$ref":"#/components/parameters/Common.Pagination.PaginationParams.limit"},{"$ref":"#/components/parameters/Groups.GroupListParams.orderTitle"}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Groups.GroupResource"}},"meta":{"$ref":"#/components/schemas/Common.Pagination.PaginationMeta"}},"description":"JSON:API document wrapping a collection of resources with pagination meta."}}}},"401":{"description":"Authentication credentials are missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Unauthorized"}}}},"422":{"description":"The request has missing or invalid arguments; `details` lists the messages per argument.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Common.Errors.InvalidArguments"},{"$ref":"#/components/schemas/Common.Errors.InvalidNestedArguments"}]}}}}},"tags":["Groups"]}}}}
```