Skip to main content
Telepath

GET List Trunks

Get all SIP trunks (connections).

endpoint 
GET https://api.telepathvoice.com/v1/trunks

Overview

Retrieve all SIP trunks configured in your account. Each trunk represents a connection that links an AI voice agent to a SIP identity. Results are paginated and can be filtered by status.

Request

Query Parameters

limit integer Maximum number of trunks to return. Range: 1–100. Default: 20.
offset integer Number of trunks to skip for pagination. Default: 0.
status string Filter by trunk status. One of: active, inactive, error.

Example Request

bash 
curl -X GET "https://api.telepathvoice.com/v1/trunks?limit=20&offset=0" \
  -H "Authorization: Bearer sk_live_abc123def456..." \
  -H "Content-Type: application/json"

Python Example

python 
import requests

API_KEY = "sk_live_abc123def456..."
BASE_URL = "https://api.telepathvoice.com/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

params = {
    "limit": 20,
    "offset": 0,
    "status": "active"
}

response = requests.get(f"{BASE_URL}/trunks", headers=headers, params=params)
data = response.json()
print(f"Found {data['pagination']['total']} trunks")
for trunk in data["trunks"]:
    print(f"  {trunk['id']}: {trunk['name']} ({trunk['status']})")

Response

Response Fields

trunks array Array of trunk objects.
trunks[].id string Unique trunk identifier (e.g., conn_abc123xyz).
trunks[].name string Friendly name for this trunk.
trunks[].status string Current status: active, inactive, or error.
trunks[].ai_provider string AI provider type: openai, elevenlabs, or custom.
trunks[].sip_username string SIP authentication username.
trunks[].created_at string ISO 8601 timestamp when the trunk was created.
trunks[].updated_at string ISO 8601 timestamp of the last update.
trunks[].metrics object Performance metrics for this trunk.
trunks[].metrics.calls_today integer Number of calls processed today.
trunks[].metrics.success_rate number Call success rate as a percentage (0–100).
trunks[].metrics.avg_latency_ms integer Average end-to-end latency in milliseconds.
pagination object Pagination metadata.
pagination.limit integer The limit value used for this request.
pagination.offset integer The offset value used for this request.
pagination.total integer Total number of trunks matching the query.

Example Response

json 
{
  "trunks": [
    {
      "id": "conn_abc123xyz",
      "name": "Production OpenAI Agent",
      "status": "active",
      "ai_provider": "openai",
      "sip_username": "agent-prod-01",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-03-01T14:22:00Z",
      "metrics": {
        "calls_today": 142,
        "success_rate": 98.6,
        "avg_latency_ms": 187
      }
    },
    {
      "id": "conn_def456uvw",
      "name": "Staging ElevenLabs Agent",
      "status": "inactive",
      "ai_provider": "elevenlabs",
      "sip_username": "agent-staging-01",
      "created_at": "2024-02-10T09:00:00Z",
      "updated_at": "2024-02-28T11:45:00Z",
      "metrics": {
        "calls_today": 0,
        "success_rate": 95.2,
        "avg_latency_ms": 210
      }
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 2
  }
}

Error Responses

Unauthorized (401)

json 
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key",
    "status": 401
  }
}

Invalid Parameters (400)

json 
{
  "error": {
    "code": "invalid_parameters",
    "message": "limit must be between 1 and 100",
    "status": 400
  }
}

Usage Examples

Pagination

python 
def get_all_trunks(api_key):
    """Fetch all trunks using pagination."""
    BASE_URL = "https://api.telepathvoice.com/v1"
    headers = {"Authorization": f"Bearer {api_key}"}
    all_trunks = []
    offset = 0
    limit = 100

    while True:
        r = requests.get(
            f"{BASE_URL}/trunks",
            headers=headers,
            params={"limit": limit, "offset": offset}
        )
        data = r.json()
        all_trunks.extend(data["trunks"])
        if offset + limit >= data["pagination"]["total"]:
            break
        offset += limit

    return all_trunks

Filter by Status

python 
# Get only trunks in error state
r = requests.get(
    f"{BASE_URL}/trunks",
    headers=headers,
    params={"status": "error"}
)
error_trunks = r.json()["trunks"]
print(f"{len(error_trunks)} trunks need attention")

Monitor Performance

python 
r = requests.get(f"{BASE_URL}/trunks", headers=headers)
trunks = r.json()["trunks"]

for trunk in trunks:
    m = trunk["metrics"]
    if m["success_rate"] < 95 or m["avg_latency_ms"] > 300:
        print(f"ALERT: {trunk['name']} — "
              f"success={m['success_rate']}%, latency={m['avg_latency_ms']}ms")

See Also