List all team members

List all team members and pending invitations.

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 e-mail address. If provided, returns a single member or invitation object instead of a list.

page

integer

The page number to return, starting with 1.

per_page

integer

Number of results per page. Defaults to 50, maximum 250.

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",
        "role_id": 101,
        "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",
        "role_id": 104,
        "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",
        "role_id": 206,
        "mobile_app_platforms": []
      }
    },
    {
      "id": "201",
      "type": "team_member_invitation",
      "attributes": {
        "email": "charlie@example.com",
        "invited_at": "2023-10-28T12:00:00.000Z",
        "role": "member",
        "role_id": 105
      }
    }
  ],
  "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",
      "role_id": 101,
      "mobile_app_platforms": [
        "ios"
      ]
    }
  }
}

404

No team member or invitation with the specified e-mail 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."
}

Response attributes

string

The ID of the user, or of the invitation for a pending invitation.

type

string

team_member for a member, or team_member_invitation for a pending invitation.

attributes.email

string

The e-mail address of the member or invitee.

attributes.first_name

string or null

The first name of the member, or null when it isn't set, and left out on invitations.

attributes.last_name

string or null

The last name of the member, or null when it isn't set, and left out on invitations.

attributes.created_at

string

When the member's Better Stack account was created, in ISO 8601 format, and left out on invitations.

attributes.invited_at

string

When the invitation was sent, in ISO 8601 format, on invitations only.

attributes.role

string or null

The role in the team your API token is scoped to: admin, billing_admin, team_lead, responder, member, or custom for a custom role, which an invitation returns as null instead.

attributes.role_id

integer

The ID of the role, the id of a role from List roles as a number.

attributes.mobile_app_platforms

array

The platforms the member's mobile apps receive push notifications on, ios and android, empty when none, and left out on invitations.

pagination.first

string

The URL of the first page. Read more about pagination.

pagination.last

string

The URL of the last page.

pagination.prev

string or null

The URL of the previous page, or null on the first page.

pagination.next

string or null

The URL of the next page, or null on the last page.

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"

Batch remove catalog records

Get a single team member

Explore documentation

List all team members

Example cURL

Please accept cookies