# List all teams

Lists all teams in your organization, ordered by ID. Needs a [global API token](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#get-a-global-api-token) or a signed-in user's OAuth token, which reads only the teams the user belongs to.

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

[[query_param]]
name = "page"
description = "The page number to return, starting with `1`."
required = false
type = "integer"

[[query_param]]
name = "per_page"
description = "Number of results per page. Defaults to `50`, maximum `250`."
required = false
type = "integer"

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

[responses]
[[response]]
status = 200
description = '''Returns a list of your organization's teams.'''
body = '''{
  "data": [
    {
      "id": "t123",
      "type": "team",
      "attributes": {
        "name": "Platform team",
        "created_at": "2026-11-16T09:00:00.000Z",
        "updated_at": "2026-11-16T09:00:00.000Z",
        "incident_grouping_period": 300,
        "incident_grouping_metadata_scope": ["Origin"],
        "notify_about_all_incidents_in_a_group": true,
        "reporting_enabled": false,
        "opened_emails_tracking_enabled": true,
        "on_call_reminder_lead_time": 86400,
        "on_call_reminder_sms": false,
        "on_call_reminder_email": true,
        "on_call_reminder_push": true
      }
    }
  ],
  "pagination": {
    "first": "https://betterstack.com/api/v2/teams?page=1",
    "last": "https://betterstack.com/api/v2/teams?page=1",
    "prev": null,
    "next": null
  }
}'''

[[response]]
status = 401
description = '''Returned for a missing or invalid token, or a team API token.'''
body = '''{
  "errors": "We could not authenticate your request. Please provide a valid Global API token or Better Stack OAuth token."
}'''
[/responses]

[params]
title = "Response attributes"

[[param]]
name = "id"
type = "string"
description = "The ID of the team, like `t123`."

[[param]]
name = "type"
type = "string"
description = "Always `team`."

[[param]]
name = "attributes.name"
type = "string"
description = "The name of the team."

[[param]]
name = "attributes.created_at"
type = "string"
description = "When the team was created, in ISO 8601 format."

[[param]]
name = "attributes.updated_at"
type = "string"
description = "When the team was last updated, in ISO 8601 format."

[[param]]
name = "attributes.incident_grouping_period"
type = "integer"
description = "Incidents triggered within this many seconds of each other are grouped. `0` means incidents are never grouped."

[[param]]
name = "attributes.incident_grouping_metadata_scope"
type = "array or null"
description = "Metadata keys that keep incidents apart: incidents whose values for these keys differ are never grouped."

[[param]]
name = "attributes.notify_about_all_incidents_in_a_group"
type = "boolean"
description = "Whether every incident in a group notifies, or only the first one."

[[param]]
name = "attributes.reporting_enabled"
type = "boolean"
description = "Whether reporting is on for the team."

[[param]]
name = "attributes.opened_emails_tracking_enabled"
type = "boolean"
description = "Whether the incident timeline shows when a team member opens the incident e-mail."

[[param]]
name = "attributes.on_call_reminder_lead_time"
type = "integer"
description = "How many seconds before their on-call shift starts responders get a reminder, or `0` for no reminder."

[[param]]
name = "attributes.on_call_reminder_sms"
type = "boolean"
description = "Whether the on-call reminder is sent by SMS."

[[param]]
name = "attributes.on_call_reminder_email"
type = "boolean"
description = "Whether the on-call reminder is sent by e-mail."

[[param]]
name = "attributes.on_call_reminder_push"
type = "boolean"
description = "Whether the on-call reminder is sent by push notification."

[[param]]
name = "pagination.first"
type = "string"
description = "The URL of the first page. Read more about [pagination](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#pagination)."

[[param]]
name = "pagination.last"
type = "string"
description = "The URL of the last page."

[[param]]
name = "pagination.prev"
type = "string or null"
description = "The URL of the previous page, or `null` on the first page."

[[param]]
name = "pagination.next"
type = "string or null"
description = "The URL of the next page, or `null` on the last page."
[/params]

#### Example cURL

```shell
[label Example]
curl --request GET \
  --url https://betterstack.com/api/v2/teams \
  --header "Authorization: Bearer $TOKEN"
```
