---
title: "List cost thresholds"
method: GET
path: "/v1/cost-thresholds"
tags: ["Cost Thresholds"]
---

# List cost thresholds

`GET /v1/cost-thresholds`

## Request

- Base URL: `https://api.telgea.com`
- URL: `https://api.telgea.com/v1/cost-thresholds`
- Auth: API key in header `x-api-key`

Lists what people in your organization may spend per month on a usage type: the organization's own threshold; with `teamId`, that team's own and the own thresholds of the people in it; with `userId`, that user's own. A threshold that opens next month is listed with its `validFrom` in the future. Omit `usageType` for every type.

A team or user of another organization answers `404`; a usage type nothing can enforce yet answers `422`. A user falls under their own threshold, else their team's, else the organization's. To see which one a user is under, with their spend this month, use `GET /v1/users/{userId}/cost-thresholds/{usageType}`.

`currency` is the money a threshold written for the named team or user would carry: their cost-center currency, else the organization's primary.

**Scope:** `policies:read`, and `teams:read` when a team is named.

## Query parameters

- `usageType` 'DATA' | 'VOICE' | 'SMS' | 'MMS': The usage type the threshold is on. `VOICE` is international calling: reaching it pauses international calls and SMS on the person's lines, where their market offers the pause. Other types answer `422` until the platform can enforce them.
- `teamId` string, uuid: UUID of the team the threshold is for. Omit with `userId` for the organization's own.
- `userId` string, uuid: UUID of the user the threshold is for. Omit with `teamId` for the organization's own.

## Response `200`

The thresholds in force or opening next month.

- ListCostThresholdsResponse
  - `thresholds` CostThreshold[], required: The organization's thresholds in force or opening next month, and the named team's or user's own.
    - `id` string, required: UUID of the threshold.
    - `usageType` 'DATA' | 'VOICE' | 'SMS' | 'MMS', required: The usage type the threshold is on. `VOICE` is international calling: reaching it pauses international calls and SMS on the person's lines, where their market offers the pause. Other types answer `422` until the platform can enforce them.
    - `scope` 'organization' | 'team' | 'user', required: Whose threshold this is: the organization's default, a team's, or one user's own.
    - `teamId` string, nullable, required: The team, for a team threshold.
    - `userId` string, nullable, required: The user, for a user threshold.
    - `maxAmount` number, required: What one person may spend on the usage type per month, in `currency`.
    - `currency` string, required: ISO 4217 code of the threshold's money: the team's cost-center currency, else the organization's primary.
    - `period` 'monthly', required: The period the spend is counted in. Always the calendar month.
    - `validFrom` string, required: When the threshold opens (ISO 8601). A threshold lowered below someone's spend opens next month.
    - `validTo` string, nullable, required: When the threshold closes (ISO 8601), or null while it stands.
  - `currency` string: ISO 4217 code a threshold written for the named team or user would carry. Absent when neither is named.

## Other responses

- `400`: Request failed schema validation, or named both a team and a user
- `401`: Missing or invalid API key in the X-API-Key header
- `403`: Insufficient permissions to view policies
- `404`: No team in your organization has this id, so nothing was read or changed. No user in your organization has this id, so nothing was read or changed.
- `422`: No threshold can stand on this usage type yet, so nothing was read or changed.
- `429`: The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets.
- `500`: Internal server error. Contact support if this persists.

---

[API](https://skmtc.dev/telgea/apis/telgea-api.md) - [All operations](https://skmtc.dev/telgea/apis/telgea-api/llms.txt) - [OpenAPI document](https://skmtc.dev/telgea/apis/telgea-api/revisions/4e8f8c04fe9e?raw)