Skip to main content
GET
/
v1
/
calls
curl "https://api.ringyo.ai/v1/calls?limit=10&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": "call_xyz789",
      "status": "completed",
      "phone_number": "+14155551234",
      "from_number": "+18005551234",
      "agent_id": "agent_abc123",
      "duration": 245,
      "metadata": {
        "customer_id": "cust_456"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "ended_at": "2024-01-15T10:34:05Z"
    },
    {
      "id": "call_abc456",
      "status": "completed",
      "phone_number": "+14155559876",
      "from_number": "+18005551234",
      "agent_id": "agent_abc123",
      "duration": 180,
      "metadata": {},
      "created_at": "2024-01-15T09:15:00Z",
      "ended_at": "2024-01-15T09:18:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNVQwOToxNTowMFoifQ==",
  "total": 156
}

​
Request

Retrieve a paginated list of calls for your account with optional filtering.

​
Headers

​
Authorization
string
required
Bearer token for authentication. Format: Bearer YOUR_API_KEY

​
Query Parameters

​
limit
integer
default:"20"
Number of calls to return (1-100)
​
cursor
string
Pagination cursor from a previous response
​
status
string
Filter by status: queued, ringing, in_progress, completed, failed, no_answer, busy
​
agent_id
string
Filter by agent ID
​
phone_number
string
Filter by destination phone number
​
from_date
string
Filter calls created after this ISO 8601 date
​
to_date
string
Filter calls created before this ISO 8601 date
​
order
string
default:"desc"
Sort order: asc or desc (by created_at)

​
Response

​
data
array
Array of call objects
​
has_more
boolean
Whether there are more results available
​
next_cursor
string
Cursor to use for fetching the next page
​
total
integer
Total number of calls matching the filter
curl "https://api.ringyo.ai/v1/calls?limit=10&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": "call_xyz789",
      "status": "completed",
      "phone_number": "+14155551234",
      "from_number": "+18005551234",
      "agent_id": "agent_abc123",
      "duration": 245,
      "metadata": {
        "customer_id": "cust_456"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "ended_at": "2024-01-15T10:34:05Z"
    },
    {
      "id": "call_abc456",
      "status": "completed",
      "phone_number": "+14155559876",
      "from_number": "+18005551234",
      "agent_id": "agent_abc123",
      "duration": 180,
      "metadata": {},
      "created_at": "2024-01-15T09:15:00Z",
      "ended_at": "2024-01-15T09:18:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNVQwOToxNTowMFoifQ==",
  "total": 156
}

​
Pagination

Use cursor-based pagination for efficient traversal of large result sets: 
let cursor = null;
let allCalls = [];

do {
  const params = new URLSearchParams({ limit: '100' });
  if (cursor) params.set('cursor', cursor);

  const response = await fetch(
    `https://api.ringyo.ai/v1/calls?${params}`,
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
  );

  const { data, has_more, next_cursor } = await response.json();
  allCalls = allCalls.concat(data);
  cursor = has_more ? next_cursor : null;
} while (cursor);

​
Error Codes

CodeDescription
invalid_cursorThe pagination cursor is invalid or expired
invalid_date_formatDate parameters must be ISO 8601 format