---
title: "Get the phone number allowance"
method: GET
path: "/v1/phone-number/allowance"
tags: ["Phone Number"]
---

# Get the phone number allowance

`GET /v1/phone-number/allowance`

## Request

- Base URL: `https://api.roark.ai`
- URL: `https://api.roark.ai/v1/phone-number/allowance`
- Auth: HTTP bearer

Returns how many numbers the organization gets for free, how many it holds, what a paid number costs a month, and whether a purchase would be admitted right now.

## Response `200`

The phone number allowance

- object
  - `data` PhoneNumberAllowanceResponse, required: How many numbers the organization gets for free and whether it may buy the next one
    - `plan` 'PAYG' | 'TEAM' | 'ENTERPRISE', required: The billing plan the allowance comes from
    - `freeLimit` integer, required: Numbers included at no charge
    - `used` integer, required: Numbers the organization holds right now
    - `paidCount` integer, required: How many of those sit outside the free allowance
    - `monthlyRentMicros` integer, required: What one paid number costs a month, in micro-dollars
    - `nextIsFree` boolean, required: Whether the next number would be free
    - `canPurchase` boolean, required: Whether a purchase would be admitted right now
    - `blockedReason` 'PAYMENT_METHOD_REQUIRED' | 'INSUFFICIENT_CREDITS' | 'SPEND_CAP_REACHED' | 'PLAN_LIMIT_REACHED', nullable, required: Why a purchase would be refused; null when canPurchase is true
    - `isOverridden` boolean, required: True when the free allowance comes from a per-organization override

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `500`: Internal Server Error

## Changes

> 188 revisions in range; 1 not diffed.

- **2026-10-26** `0fb1c3b1940a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/phone-number/allowance/get.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/efc3377249d1?raw)