Cost thresholds

The cost threshold object

What people may spend per month on a usage type, such as international calls, before it is paused.

List cost thresholds

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.

Requires the permission policies:read on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Responses

Problems this endpoint can return

curl -X GET "https://api.telgea.com/v1/cost-thresholds" \
  -H "x-api-key: $TELGEA_API_KEY"

{
  "thresholds": [
    {
      "id": "5d0b2c1e-7f3a-4b6c-9e8d-2a1f0c3b4d5e",
      "usageType": "VOICE",
      "scope": "team",
      "teamId": "2f6b0d3a-8c1e-4a7f-9b2d-1e3c4d5f6a70",
      "userId": null,
      "maxAmount": 50,
      "currency": "EUR",
      "period": "monthly",
      "validFrom": "2026-10-01T00:00:00.000Z",
      "validTo": null
    }
  ],
  "currency": "EUR"
}

Set a cost threshold

Sets what one person may spend per month on a usage type: for the organization, for a team (teamId), or for one user (userId). A new amount replaces the scope's current one on that usage type.

VOICE is international calling: once a user's spend reaches the threshold, international calls and SMS on their lines are paused until the next month, where their market offers the pause; elsewhere the threshold warns only. Other usage types answer 422 until the platform can enforce them.

The amount is in the team's cost-center currency, else the organization's primary; read it back from the response. The threshold opens now, so this month's spend counts against it at once, unless someone in scope has already spent more than the new amount: then it opens next month and appliesFromNextMonth says so. Raising it above a paused user's spend lifts their pause in the same call.

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

Requires the permission policies:write on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Request body

Responses

Problems this endpoint can return

curl -X PUT "https://api.telgea.com/v1/cost-thresholds" \
  -H "x-api-key: $TELGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "usageType": "VOICE",
  "teamId": "2f6b0d3a-8c1e-4a7f-9b2d-1e3c4d5f6a70",
  "maxAmount": 50
}'

{
  "threshold": {
    "id": "5d0b2c1e-7f3a-4b6c-9e8d-2a1f0c3b4d5e",
    "usageType": "VOICE",
    "scope": "team",
    "teamId": "2f6b0d3a-8c1e-4a7f-9b2d-1e3c4d5f6a70",
    "userId": null,
    "maxAmount": 50,
    "currency": "EUR",
    "period": "monthly",
    "validFrom": "2026-10-01T00:00:00.000Z",
    "validTo": null
  },
  "appliesFromNextMonth": false,
  "releasedNumberCount": 0
}

Remove a cost threshold

Ends the scope's threshold on a usage type now: the organization's (no team or user), a team's (teamId) or a user's own (userId). A user then falls under their team's threshold, a team under the organization's; with none left, the usage is unlimited.

Removing a threshold that is not set changes nothing and still answers 204.

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

Requires the permission policies:write on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Responses

Problems this endpoint can return

curl -X DELETE "https://api.telgea.com/v1/cost-thresholds" \
  -H "x-api-key: $TELGEA_API_KEY"

{
  "type": "https://developer.telgea.com/errors/http/BAD_REQUEST",
  "title": "Bad request",
  "status": 400,
  "detail": "This request was refused, and no more specific code describes why.",
  "code": "BAD_REQUEST",
  "requestId": "req_123"
}