Skip to main content
GET
/
agents
/
phone-numbers
Search by query
curl -G "https://api.cartesia.ai/agents/phone-numbers" \
  -H "X-API-Key: your-api-key" \
  -H "Cartesia-Version: 2026-03-01" \
  -d q="support" \
  -d limit=10
{
  "data": [
    {
      "id": "<string>",
      "number": "<string>",
      "agent": {
        "id": "<string>",
        "name": "<string>"
      },
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "provider": {
        "id": "<string>",
        "account_sid": "<string>",
        "api_key_sid": "<string>",
        "region": "us1"
      },
      "label": "<string>"
    }
  ],
  "has_more": true
}

Authorizations

​
Authorization
string
header
required

Cartesia API key (sk_car_...). Get one at play.cartesia.ai/keys.

Headers

​
Cartesia-Version
enum<string>
required

API version header.

Available options:
2026-03-01
Example:

"2026-03-01"

Query Parameters

​
agent_id
string

Filter by assigned agent ID.

​
provider_id
string

Filter by provider ID.

​
type
enum<string>

Filter by provider type.

Available options:
twilio,
cartesia
​
q
string

Search by phone number, label, or agent name.

​
starting_after
string | null

A cursor to use in pagination. starting_after is a phone number ID that defines your place in the list. For example, if you make a /agents/phone-numbers request and receive 20 objects, ending with pn_abc123, your subsequent call can include starting_after=pn_abc123 to fetch the next page of the list.

​
ending_before
string | null

A cursor to use in pagination. ending_before is a phone number ID that defines your place in the list. For example, if you make a /agents/phone-numbers request and receive 20 objects, starting with pn_abc123, your subsequent call can include ending_before=pn_abc123 to fetch the previous page of the list.

​
limit
integer | null

(Pagination option) The number of phone numbers to return per page, ranging between 1 and 100. The default page limit is 10.

Response

200 - application/json

A paginated list of phone numbers.

​
data
PhoneNumberResponse · object[]
required
​
has_more
boolean
required