# List phone numbers (/en/api-reference/api-ref/conversational-ai/platform/list-numbers)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

> Documentation: Conversational AI API.
> Documentation version: Preview.
> This document describes only this version. [Version index](/llms/doc-versions-convoai-api-v2.txt).


Retrieves the phone numbers in your project.

- OpenAPI: /openapi/conversational-ai/rest-api-platform.en.yaml
- Operation ID: list-numbers
- Method: GET
- Path: /v1/projects/{appid}/numbers
- Endpoint: https://preview.ai.agora.io/conversational-ai/v1/projects/{appid}/numbers

## Servers

- https://preview.ai.agora.io/conversational-ai

## Authorization

This endpoint requires authentication.

- `tokenAuth`
- `basicAuth`

## Parameters

- `appid` (path, required, string) - The App ID of your project.
- `limit` (query, optional, integer) - The maximum number of phone numbers to return on each page.
  - Default: `50`
  - Range: `[1, 100]`
- `cursor` (query, optional, string) - The `next_cursor` value from the previous page of results. Omit it to get the first page. The cursor is opaque, so pass it back unchanged.
- `order` (query, optional, string) - The sort order of the results:

- `create_ts.desc`: Newest first.
- `create_ts.asc`: Oldest first.
  - Allowed: `create_ts.desc` | `create_ts.asc`
  - Default: `create_ts.desc`

## Request body

No request body.

## Responses

### 200

The request was successful. The response body contains a page of phone numbers.

- `has_more` (boolean) - Whether more results are available after this page.
- `next_cursor` (string | null | null) - The cursor for the next page. Pass it in the `cursor` query parameter of your next request. `null` on the last page.
- `data` (object)
  - `data.count` (integer) - The number of phone numbers on this page.
  - `data.list` (array) - The phone numbers on this page.
    - `data.list.items` (object)
      - `data.list.items.number_id` (string) - The ID of the phone number, a UUID.
        - Format: `uuid`
      - `data.list.items.number` (string) - The phone number in E.164 format.
      - `data.list.items.description` (string) - A description of the number's purpose. It's separate from `sip_trunk.name`, which names the carrier connection.
      - `data.list.items.sip_trunk` (object)
        - `data.list.items.sip_trunk.name` (string) - The name of the carrier connection.
        - `data.list.items.sip_trunk.hostname` (string) - The carrier's SIP hostname.
        - `data.list.items.sip_trunk.port` (integer) - The SIP signaling port.
        - `data.list.items.sip_trunk.transport` (string) - The transport protocol for the carrier connection.
          - Allowed: `udp` | `tcp` | `tls`
        - `data.list.items.sip_trunk.allowed_ips` (array) - The addresses allowed to send inbound SIP traffic.
          - `data.list.items.sip_trunk.allowed_ips.items` (string)
      - `data.list.items.inbound` (object) - What happens when someone calls this number. If you omit it, inbound calls are rejected. `call_policy` is required when `agent` isn't `null`.
        - `data.list.items.inbound.agent` (string | null | null, required) - The ID of the agent that answers inbound calls. Set to `null` to reject inbound calls.
        - `data.list.items.inbound.call_policy` (object) - Limits and behavior for inbound calls to this number. Each limit you omit adds no limit.
          - `data.list.items.inbound.call_policy.max_call_duration_seconds` (integer) - The maximum length of a call in seconds, measured from when it's answered.
            - Minimum: `1`
          - `data.list.items.inbound.call_policy.max_silence_duration_ms` (integer) - Hang up when nobody on the call has spoken for this many milliseconds.
            - Minimum: `1`
          - `data.list.items.inbound.call_policy.end_call` (object) - Conditions under which the agent can end the call itself. Every condition is off unless you set it to `true`.
            - `data.list.items.inbound.call_policy.end_call.on_user_request` (boolean) - End the call when the caller clearly says goodbye or asks to hang up.
              - Default: `false`
            - `data.list.items.inbound.call_policy.end_call.on_voicemail` (boolean) - End the call when the agent reaches voicemail, such as a "please leave a message after the tone" announcement.
              - Default: `false`
            - `data.list.items.inbound.call_policy.end_call.on_ai_assistant` (boolean) - End the call when the call is answered by an AI assistant, a voice secretary, or another automated answering system.
              - Default: `false`
      - `data.list.items.create_ts` (integer) - The time the number was added, as a Unix timestamp in seconds.
### 401

Authentication is missing or invalid. The reason is `InvalidPermission`.

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).
### default

The request failed. The response body contains the `reason` and `detail` of the failure. For possible reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).

## Response examples

### 200

```json
{
  "data": {
    "count": 1,
    "list": [
      {
        "number_id": "92e68758-3d3a-4f27-8b93-3fd8d834467c",
        "number": "+14155550100",
        "description": "Primary customer support line for North America.",
        "sip_trunk": {
          "name": "support-line",
          "hostname": "acme.pstn.example.com",
          "port": 5061,
          "transport": "tls"
        },
        "inbound": {
          "agent": "3f6c2a9e-8d1b-4e7a-9c55-0b2f7d1e4a10",
          "call_policy": {
            "max_call_duration_seconds": 1800,
            "max_silence_duration_ms": 60000,
            "end_call": {
              "on_user_request": true
            }
          }
        },
        "create_ts": 1787223852
      }
    ]
  },
  "has_more": false,
  "next_cursor": null
}
```