---
title: "List teams"
method: GET
path: "/api/v2/teams"
tags: ["Teams"]
---

# List teams

`GET /api/v2/teams`

Return a list of teams.

By default, this returns the first 20 teams. Page through this list with the `limit` parameter and by following the `first`, `prev`, `next`, and `last` links in the `_links` field that returns. If those links do not appear, the pages they refer to don't exist. For example, the `first` and `prev` links will be missing from the response on the first page, because there is no previous page and you cannot return to the first page when you are already on the first page.

### Filtering teams

LaunchDarkly supports the following fields for filters:

- `query` is a string that matches against the teams' names and keys. It is not case-sensitive.
  - A request with `query:abc` returns teams with the string `abc` in their name or key.
- `nomembers` is a boolean that filters the list of teams who have 0 members
  - A request with `nomembers:true` returns teams that have 0 members
  - A request with `nomembers:false` returns teams that have 1 or more members

### Expanding the teams response
LaunchDarkly supports expanding several fields in the "List teams" response. By default, these fields are **not** included in the response.

To expand the response, append the `expand` query parameter and add a comma-separated list with any of the following fields:

* `members` includes the total count of members that belong to the team.
* `roles` includes a paginated list of the custom roles that you have assigned to the team.
* `roleAttributes` includes a list of the role attributes that you have assigned to the team.
* `projects` includes a paginated list of the projects that the team has any write access to.
* `maintainers` includes a paginated list of the maintainers that you have assigned to the team.

For example, `expand=members,maintainers` includes the `members` and `maintainers` fields in the response.

## Query parameters

- `limit` integer — The number of teams to return in the response. Defaults to 20.
- `offset` integer — Where to start in the list. Use this with pagination. For example, an offset of 10 skips the first ten items and returns the next `limit` items.
- `filter` string, string — A comma-separated list of filters. Each filter is constructed as `field:value`.
- `expand` string, string — A comma-separated list of properties that can reveal additional information in the response.

## Response `200`

Teams collection response

- Teams
  - `items` Team[], required — An array of teams
    - `description` string — A description of the team
    - `key` string — The team key
    - `name` string — A human-friendly name for the team
    - `_access` Access
      - `denied` AccessDenied[], required
        - `action` string, required
        - `reason` AccessDeniedReason, required
          - `resources` string[] — Resource specifier strings
          - `notResources` string[] — Targeted resources are the resources NOT in this list. The <code>resources</code> and <code>notActions</code> fields must be empty to use this field.
          - `actions` ActionSpecifier[] — Actions to perform on a resource
          - `notActions` ActionSpecifier[] — Targeted actions are the actions NOT in this list. The <code>actions</code> and <code>notResources</code> fields must be empty to use this field.
          - `effect` 'allow' | 'deny', required — Whether this statement should allow or deny actions on the resources.
          - `role_name` string
      - `allowed` AccessAllowedRep[], required
        - `action` string, required
        - `reason` AccessAllowedReason, required
          - `resources` string[] — Resource specifier strings
          - `notResources` string[] — Targeted resources are the resources NOT in this list. The <code>resources</code> and <code>notActions</code> fields must be empty to use this field.
          - `actions` ActionSpecifier[] — Actions to perform on a resource
          - `notActions` ActionSpecifier[] — Targeted actions are the actions NOT in this list. The <code>actions</code> and <code>notResources</code> fields must be empty to use this field.
          - `effect` 'allow' | 'deny', required — Whether this statement should allow or deny actions on the resources.
          - `role_name` string
    - `_creationDate` integer
    - `_links` object — The location and content type of related resources
    - `_lastModified` integer
    - `_version` integer — The team version
    - `_idpSynced` boolean — Whether the team has been synced with an external identity provider (IdP). Team sync is available to customers on an Enterprise plan.
    - `roleAttributes` RoleAttributeMap
    - `roles` TeamCustomRoles
      - `totalCount` integer — The number of custom roles assigned to this team
      - `items` TeamCustomRole[] — An array of the custom roles that have been assigned to this team
        - `key` string — The key of the custom role
        - `name` string — The name of the custom role
        - `projects` TeamProjects
          - `totalCount` integer
          - `items` ProjectSummary[] — Details on each project where team members have write privileges on at least one resource type (e.g. flags)
            - `_id` string, required — The ID of this project
            - `_links` object, required — The location and content type of related resources
            - `key` string, required — The project key
            - `name` string, required — The project name
        - `appliedOn` integer
      - `_links` object — The location and content type of related resources
    - `members` TeamMembers
      - `totalCount` integer — The total count of members that belong to the team
    - `projects` TeamProjects
      - `totalCount` integer
      - `items` ProjectSummary[] — Details on each project where team members have write privileges on at least one resource type (e.g. flags)
        - `_id` string, required — The ID of this project
        - `_links` object, required — The location and content type of related resources
        - `key` string, required — The project key
        - `name` string, required — The project name
    - `maintainers` TeamMaintainers
      - `totalCount` integer — The number of maintainers of the team
      - `items` MemberSummary[] — Details on the members that have been assigned as maintainers of the team
        - `_links` object, required — The location and content type of related resources
        - `_id` string, required — The member's ID
        - `firstName` string — The member's first name
        - `lastName` string — The member's last name
        - `role` string, required — The member's base role. If the member has no additional roles, this role will be in effect.
        - `email` string, required — The member's email address
      - `_links` object — The location and content type of related resources
  - `_links` object — The location and content type of related resources
  - `totalCount` integer — The number of teams

## Other responses

- `401` — Invalid access token
- `405` — Method not allowed
- `429` — Rate limited

---

[API](https://skmtc.dev/launchdarkly/apis/launchdarkly-rest-api.md) · [All operations](https://skmtc.dev/launchdarkly/apis/launchdarkly-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/launchdarkly/launchdarkly-rest-api/revisions/69c5c9aafe78/schema)