# List all team members

List all team members and pending invitations. This endpoint [supports pagination](https://betterstack.com/docs/uptime/api/pagination/).

You can also retrieve a specific member or invitation by providing an `email` query parameter.

[endpoint]
base_url = "https://betterstack.com"
path = "/api/v2/team-members"
method = "GET"

[[query_param]]
name = "team_name"
description = "Required if using a [global API token](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#get-a-global-api-token) to specify the team."
required = false
type = "string"

[[query_param]]
name = "email"
description = "Filter by a specific email address. If provided, returns a single member or invitation object instead of a list."
required = false
type = "string"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 200
description = '''Returns a list of team members and pending invitations.'''
body = '''{
  "data": [
    {
      "id": "101",
      "type": "team_member",
      "attributes": {
        "email": "alice@example.com",
        "first_name": "Alice",
        "last_name": "Smith",
        "created_at": "2023-10-26T10:00:00.000Z",
        "role": "admin",
        "mobile_app_platforms": ["ios", "android"]
      }
    },
    {
      "id": "102",
      "type": "team_member",
      "attributes": {
        "email": "bob@example.com",
        "first_name": "Bob",
        "last_name": "Johnson",
        "created_at": "2023-10-27T11:00:00.000Z",
        "role": "responder",
        "mobile_app_platforms": []
      }
    },
    {
      "id": "201",
      "type": "team_member_invitation",
      "attributes": {
        "email": "charlie@example.com",
        "invited_at": "2023-10-28T12:00:00.000Z",
        "role": "member"
      }
    }
  ],
  "pagination": {
    "first": "https://betterstack.com/api/v2/team-members?page=1",
    "last": "https://betterstack.com/api/v2/team-members?page=1",
    "prev": null,
    "next": null
  }
}'''

[[response]]
status = 200
description = '''When using the `email` parameter, returns a single object.'''
body = '''{
  "data": {
    "id": "101",
    "type": "team_member",
    "attributes": {
      "email": "alice@example.com",
      "first_name": "Alice",
      "last_name": "Smith",
      "created_at": "2023-10-26T10:00:00.000Z",
      "role": "admin",
      "mobile_app_platforms": ["ios"]
    }
  }
}'''

[[response]]
status = 404
description = '''No team member or invitation with the specified email was found.'''
body = '''{
  "errors": "Team member with email \"nonexistent@example.com\" not found"
}'''

[[response]]
status = 422
description = '''A global API token has access to multiple teams, and no `team_name` was provided.'''
body = '''{
  "errors": "This token has access to multiple teams. Please use the 'team_name' parameter to specify the team."
}'''

[[response]]
status = 401
description = '''Authentication failed due to missing or invalid token.'''
body = '''{
  "errors": "We could not authenticate your request. Please provide a valid Global API token or Uptime API token."
}'''
[/responses]

#### Example cURL

[code-tabs]
```shell
[label List all members]
curl --request GET \
  --url "https://betterstack.com/api/v2/team-members" \
  --header "Authorization: Bearer $TOKEN"
```
```shell
[label Find by email]
curl --request GET \
  --url "https://betterstack.com/api/v2/team-members?email=alice@example.com" \
  --header "Authorization: Bearer $TOKEN"
```
[/code-tabs]