List all team members

List all team members and pending invitations. This endpoint supports pagination.

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

The role attribute returned for each team member is the user's role in the team your API token is scoped to. A user with different roles in different teams returns different values depending on which team's token you use. Possible values: admin, billing_admin, team_lead, responder, member, or custom. custom is returned when the user has a non-system custom role.

GET https://betterstack.com/api/v2/team-members

Query parameters

team_name

string

Required if using a global API token to specify the team.

string

Filter by a specific email address. If provided, returns a single member or invitation object instead of a list.

Headers

Authorization

required string

Bearer $TOKEN

200

Returns a list of team members and pending invitations.

Response 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": "103",
      "type": "team_member",
      "attributes": {
        "email": "dana@example.com",
        "first_name": "Dana",
        "last_name": "Lee",
        "created_at": "2023-10-28T09:30:00.000Z",
        "role": "custom",
        "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
  }
}

200

When using the email parameter, returns a single object.

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

404

No team member or invitation with the specified email was found.

Response body

{
  "errors": "Team member with email \"nonexistent@example.com\" not found"
}

422

A global API token has access to multiple teams, and no team_name was provided.

Response body

{
  "errors": "This token has access to multiple teams. Please use the 'team_name' parameter to specify the team."
}

401

Authentication failed due to missing or invalid token.

Response body

{
  "errors": "We could not authenticate your request. Please provide a valid Global API token or Uptime API token."
}

Example cURL

List all members Find by email

Copied!

curl --request GET \
  --url "https://betterstack.com/api/v2/team-members" \
  --header "Authorization: Bearer $TOKEN"

curl --request GET \
  --url "https://betterstack.com/api/v2/team-members?email=alice@example.com" \
  --header "Authorization: Bearer $TOKEN"

Response attributes

Get a single team member

Explore documentation

List all team members

Example cURL

Please accept cookies