---
title: "Phone availability summary"
method: GET
path: "/phones/availability"
tags: ["phones"]
---

# Phone availability summary

`GET /phones/availability`

Returns a capacity snapshot to check before POST /phones:allocate: shared-pool availability broken down by phone type and by location, plus the caller org's dedicated phones with how many are idle (claimable right now). Optional phone_type and location filters narrow every count. Advisory only - availability can change between this read and an allocate, so allocation remains the authority and can still refuse.

## Query parameters

- `phone_type` 'android' | 'iphone' — Only count phones of this platform.
- `location` string — Only count phones at this location slug.

## Response `200`

OK

- PhoneAvailabilityResponse — Phone availability summary: shared-pool capacity plus the caller org's dedicated idle counts. An advisory snapshot - allocation is the authority and can still refuse.
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `dedicated` PhoneDedicatedAvailability, required — The caller org's dedicated-phone availability summary.
    - `by_type` PhoneDedicatedTypeAvailabilityEntry[], nullable, required — Counts per phone type.
      - `idle` integer, required — Phones claimable right now: active, unallocated, rental still usable.
      - `phone_type` string, required — Phone platform (android/iphone).
      - `total` integer, required — Active dedicated phones of this type with a usable rental.
    - `idle` integer, required — Dedicated phones claimable right now.
    - `total` integer, required — Active dedicated phones with a usable rental.
  - `shared` PhoneSharedAvailability, required — Shared-pool availability summary.
    - `available` integer, required — Shared phones free to allocate right now, across every type and location in the response.
    - `by_location` PhoneLocationAvailabilityEntry[], nullable, required — Counts per active location; locations with zero shared phones still appear.
      - `available` integer, required — Phones free to allocate at this location right now.
      - `city` string, required — City name for this location.
      - `location` string, required — Location slug identifier.
      - `region` string, required — Broader geographic region label.
      - `state` string, required — State or region name for this location.
      - `total` integer, required — Active shared phones at this location.
    - `by_type` PhoneTypeAvailabilityEntry[], nullable, required — Counts per phone type.
      - `available` integer, required — Phones free to allocate right now.
      - `phone_type` string, required — Phone platform (android/iphone).
      - `total` integer, required — Active phones of this type in the shared pool.
    - `total` integer, required — Active shared phones, across every type and location in the response.

## Other responses

- `default` — Error

---

[API](https://skmtc.dev/axilioai/apis/axilio-api.md) · [All operations](https://skmtc.dev/axilioai/apis/axilio-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/axilioai/axilio-api/revisions/8a66f81813b3/schema)