Create an alert team Beta
POST /api/v1/alerting/teams
Put people in a named group, so a monitor can alert "Support" rather than eight addresses.
Needs an X-API-Key header whose owner has permission to manage uptime monitors in the app. The call counts once against your daily quota. See Monitoring API: getting started for authentication, rate limits and errors.
Body
| Field | Type | Description |
|---|---|---|
name required | string | The team name. Up to 120 characters. |
userIds optional | integer[] | Ids of people in your workspace, up to 200. |
contactIds optional | string[] | Ids of your alert contacts, up to 200. |
- A team needs at least one person, from either list.
- An unknown contact id returns
400. A user id that isn't in your workspace is quietly ignored, so check theuserIdsthat come back. - A workspace can have up to 50 teams.
Request
Response
201 Created with the team.
201 · application/json
- {
- "team": {
- "id": "tm_2c7e91a4b6d0f3e85a17",
- "name": "Support",
- "userIds": [42, 57],
- "users": [
- { "id": 42, "name": "Sam Taylor", "email": "[email protected]" },
- { "id": 57, "name": "Ada Okoro", "email": "[email protected]" }
- ],
- "contactIds": ["ct_5b8d1f0a9c2e4d6f7a83"],
- "contacts": [{ "id": "ct_5b8d1f0a9c2e4d6f7a83", "name": "Night shift" }],
- "createdAt": "2026-09-17T09:10:40.000Z",
- "updatedAt": "2026-09-17T09:10:40.000Z"
- },
- "usage": { "used": 49, "dailyLimit": 100, "tier": "free" }
- }
Errors
| Status | When |
|---|---|
400 | No name, nobody in the team, or an unknown contact id. |
401 | The API key is missing or invalid. |
403 | The key's owner doesn't have permission to change alert contacts, or the key isn't linked to a workspace. |
405 | The endpoint doesn't accept that method. |
409 | The workspace already has 50 teams. |
429 | A rate limit or your daily quota was hit. Read Retry-After, in seconds. Writes are also limited to 30 a minute per key. |
500, 503 | Something went wrong, or the API is temporarily unavailable. Try again. |
Errors are JSON: { "error": "message" }. See Monitoring API errors.
Related
- Update a team: change its members
- Monitor settings: send a monitor's alerts to this team