# Update a team

Renames a team or changes its settings. Only the attributes you send change. Needs a [global API token](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#get-a-global-api-token) that isn't read-only.

A setting your plan doesn't include returns `422` only when the request changes it. Re-sending the current value always works. When any attribute is refused, nothing changes.

[endpoint]
base_url = "https://betterstack.com"
path = "/api/v2/teams/{id}"
method = "PATCH"

[[path_param]]
name = "id"
description = "The ID of the team, like `t123`. The number alone, like `123`, works too."
required = true
type = "string"

[[body_param]]
name = "name"
description = "The name of the team. Must be unique in your organization, ignoring case."
required = false
type = "string"

[[body_param]]
name = "incident_grouping_period"
description = "Group incidents triggered within this many seconds of each other, for example `300` for 5 minutes. `0` never groups incidents."
required = false
type = "integer"

[[body_param]]
name = "incident_grouping_metadata_scope"
description = "Metadata keys that keep incidents apart: incidents whose values for these keys differ are never grouped, for example `[\"environment\"]` to separate staging and production incidents."
required = false
type = "array"

[[body_param]]
name = "notify_about_all_incidents_in_a_group"
description = "Notify about every incident in a group. Set to `false` to be notified only about the first incident in a group."
required = false
type = "boolean"

[[body_param]]
name = "reporting_enabled"
description = "Turn on reporting, which unlocks the reports in Incidents. Needs a plan with reporting."
required = false
type = "boolean"

[[body_param]]
name = "opened_emails_tracking_enabled"
description = "Add an event to the incident timeline when a team member opens the incident e-mail. Turning it off needs a plan that lets you configure the incident timeline."
required = false
type = "boolean"

[[body_param]]
name = "on_call_reminder_lead_time"
description = "How many seconds before their on-call shift starts responders get a reminder: `0` for never, `3600`, `21600`, `43200`, `86400`, `172800` or `604800`. Changing it to any value except `0` needs a plan with on-call scheduling."
required = false
type = "integer"

[[body_param]]
name = "on_call_reminder_sms"
description = "Send the on-call reminder by SMS. Needs a plan with on-call scheduling and SMS alerts."
required = false
type = "boolean"

[[body_param]]
name = "on_call_reminder_email"
description = "Send the on-call reminder by e-mail. Needs a plan with on-call scheduling."
required = false
type = "boolean"

[[body_param]]
name = "on_call_reminder_push"
description = "Send the on-call reminder by push notification. Needs a plan with on-call scheduling and push notifications."
required = false
type = "boolean"

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

[[header]]
name = "Content-Type"
description = "application/json"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 200
description = '''Returns the updated team.'''
body = '''{
  "data": {
    "id": "t123",
    "type": "team",
    "attributes": {
      "name": "Platform engineering",
      "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": 3600,
      "on_call_reminder_sms": false,
      "on_call_reminder_email": true,
      "on_call_reminder_push": true
    }
  }
}'''

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

[[response]]
status = 403
description = '''Returned for a read-only global API token.'''
body = '''{
  "errors": "This API token is read-only and cannot be used for write operations."
}'''

[[response]]
status = 404
description = '''Your organization has no team with the given ID.'''
body = '''{
  "errors": "Resource type team with id = t123 was not found"
}'''

[[response]]
status = 422
description = '''Returned when `name` is empty, not a string, or already taken.'''
body = '''{
  "errors": "Name has already been taken"
}'''

[[response]]
status = 422
description = '''Returned when a setting has an invalid value or needs a plan your organization isn't on.'''
body = '''{
  "errors": "On-call reminder lead time must be one of 0, 3600, 21600, 43200, 86400, 172800, or 604800 seconds."
}'''

[[response]]
status = 503
description = '''Try again later.'''
body = ''''''
[/responses]

#### Example cURL

```shell
[label Example]
curl --request PATCH \
  --url https://betterstack.com/api/v2/teams/t123 \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Platform engineering",
    "on_call_reminder_lead_time": 3600
  }'
```
