---
title: "Retrieve spend caps"
description: "The workspace's monthly spend caps and what each has counted this period. `GET /api/v1/spend-caps`"
url: https://www.unitpost.com/docs/platform/get-spend-caps
section: "Platform API reference"
updated: 2026-11-17
---
# Retrieve spend caps

`GET /api/v1/spend-caps`

The workspace's monthly spend caps and what each has counted this period. `sms_purchases` caps the SMS carrier purchases API keys and apps confirm (`POST /sms/quotes/{id}/confirm`): the fee due now plus the first month of a monthly fee, per UTC calendar month; dashboard purchases never count. `cap_cents` is the cap as set (null: none, so every API purchase is refused with `403 api_spend_cap_not_set`); the cap that applies is the lower of it and `max_cents` ($1,000 a month by default). A workspace that starts a paid plan on its own card starts with a $75 cap when it has none, unless a key or app of it already holds `sms:purchase` (a workspace its organization pays for follows the organization Owner's rules instead; a key still needs `sms:purchase` to buy). `shared_plan` is the workspace's cap on its organization's shared plan and what it drew from it this period (null when it isn't on one); its organization sets it. Requires the `sms:read` or `sms:purchase` or `spend_caps:write` capability.

## Response fields (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | — |
| `sms_purchases` | object | yes | SMS purchases by API (`POST /sms/quotes/{id}/confirm`). Purchases made in the dashboard never count. |
| `shared_plan` | object \| null | no | The workspace's cap on its organization's shared plan, read-only: its organization sets it (`PATCH /organizations/{id}/shared-plan/workspaces/{workspace_id}`). Null when the workspace isn't on a shared plan. |

## Responses

| Status | Description |
| --- | --- |
| 200 | The spend caps. |
| 401 | Missing or invalid API key. |
| 403 | Insufficient scope. |
| 404 | SMS is not enabled. |
| 422 | A query key (this operation takes none). |

## Example request

```bash
curl -X GET 'https://www.unitpost.com/api/v1/spend-caps' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
```

## Example response (200)

```json
{
  "object": "spend_caps",
  "sms_purchases": {
    "cap_cents": 0,
    "max_cents": 0,
    "spent_cents": 0,
    "period_start": "string",
    "period_end": "string"
  },
  "shared_plan": {
    "cap_cents": 0,
    "spent_cents": 0,
    "period_start": "string",
    "period_end": "string"
  }
}
```

## Links

- HTML reference (with Node.js, Python, Ruby, PHP, Laravel, Go, Java, Rust, .NET and CLI examples): https://www.unitpost.com/docs/platform/get-spend-caps
- OpenAPI 3.1 (full schemas): https://www.unitpost.com/api/v1/openapi.json
