Query Calls

This endpoint provides powerful filtering and querying capabilities for retrieving call records with support for pagination, sorting, searching, and advanced column-based filtering.

Endpoint Details

URL: /calls/query
Method: GET
Authentication: Required (API KEY or JWT Token)
Source: src/types/calls_services/query.rs

Query Parameters

Basic Filters

Parameter	Type	Description	Example
`campaign_id`	`UUID` (optional)	Filter by specific campaign	`550e8400-e29b-41d4-a716-446655440000`
`ai_agent_id`	`UUID` (optional)	Filter by specific AI agent	`550e8400-e29b-41d4-a716-446655440001`
`status`	`String` (optional)	Filter by call status (case-insensitive partial match)	`completed`, `failed`, `in-progress`
`search`	`String` (optional)	Search across multiple fields (call_to, notes, feedback, transcript)	`John Doe` or `+1234567890`

Date Range Filters

Parameter	Type	Description	Example
`start_date`	`Date` (optional)	Filter calls started on or after this date	`2024-01-01`
`end_date`	`Date` (optional)	Filter calls started on or before this date	`2024-12-31`

Pagination

Parameter	Type	Description	Default	Example
`page`	`Integer`	Page number (0-indexed)	`0`	`2`
`per_page`	`Integer`	Number of results per page	`10`	`25`

Sorting

Parameter	Type	Description	Default	Example
`sort_column`	`String`	Column to sort by	`created_at`	See supported columns below
`order`	`String`	Sort order	`desc`	`asc` or `desc`

Supported Sort Columns

name (sorts by call_to)
created_at
updated_at
started_at
ended_at
call_duration
call_sid
call_from
call_to
call_provider
call_status
call_direction
call_rating
call_feedback
record_url
transcript
transcript_language
is_test
cost
price_unit
latency
disconnect_reason
analysis_sentiment
agent_task_status
agent_task_feedback
metadata
notes
agent_dynamic_variables
agent_post_call_outcomes
retry_at

Advanced Column Filtering

The API supports dynamic filtering on specific columns using three array parameters that work together:

Parameter	Type	Description
`filter_columns[]`	`Array<String>`	Column names to filter on
`filter_values[]`	`Array<String>`	Values to filter for (parallel to columns)
`filter_operator[]`	`Array<String>`	Operators to use (parallel to columns)

Supported Filter Columns

Text Fields

Columns: call_direction, call_status, call_to, call_from, transcript, notes, call_feedback, call_sid, call_provider, disconnect_reason, analysis_sentiment, agent_task_status, agent_task_feedback, price_unit Supported Operators:

EQUALS - Exact match
NOT_EQUALS - Not equal to value
CONTAINS - Contains substring (case-insensitive)
NOT_CONTAINS - Does not contain substring
NOT_NULL - Field has a value
IS_NULL - Field is null/empty
INCLUDES - Same as EQUALS (for compatibility)
NOT_INCLUDES - Same as NOT_EQUALS

Numeric Fields

Columns: call_duration (integer), call_rating (integer), cost (float), latency (integer) Supported Operators:

EQUALS - Exact match
NOT_EQUALS - Not equal to value
GREATER_THAN - Greater than value
GREATER_OR_EQUAL - Greater than or equal to value
LOWER_THAN - Less than value
LOWER_OR_EQUAL - Less than or equal to value
NOT_NULL - Field has a value
IS_NULL - Field is null

Boolean Fields

Column: is_test Supported Operators:

EQUALS - Match boolean value (true/false)
NOT_EQUALS - Not equal to boolean value
NOT_NULL - Field has a value
IS_NULL - Field is null

UUID Fields

Column: id Supported Operators:

EQUALS - Exact UUID match
NOT_EQUALS - Not equal to UUID
NOT_NULL - Field has a value
IS_NULL - Field is null

Automatic Status Updates

The endpoint automatically updates stale call statuses before querying:

Calls with status in-progress for more than 360 minutes are marked as ended
Calls with status pstn-queued for more than 5 minutes are marked as unreachable

Example Requests

Basic Query

curl -X GET "https://api.callab.ai/calls/query?page=0&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter by Campaign and Date Range

curl -X GET "https://api.callab.ai/calls/query?campaign_id=550e8400-e29b-41d4-a716-446655440000&start_date=2024-01-01&end_date=2024-01-31&sort_column=started_at&order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Search with Status Filter

curl -X GET "https://api.callab.ai/calls/query?search=John&status=completed&per_page=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Advanced Column Filtering - Multiple Conditions

curl -X GET "https://api.callab.ai/calls/query?\
filter_columns[]=call_duration&\
filter_values[]=60&\
filter_operator[]=GREATER_THAN&\
filter_columns[]=call_status&\
filter_values[]=completed&\
filter_operator[]=EQUALS&\
filter_columns[]=is_test&\
filter_values[]=false&\
filter_operator[]=EQUALS" \
  -H "Authorization: Bearer YOUR_API_KEY"

Complex Query Example

curl -X GET "https://api.callab.ai/calls/query?\
ai_agent_id=550e8400-e29b-41d4-a716-446655440001&\
start_date=2024-01-01&\
end_date=2024-12-31&\
filter_columns[]=call_direction&\
filter_values[]=outbound&\
filter_operator[]=EQUALS&\
filter_columns[]=cost&\
filter_values[]=0.50&\
filter_operator[]=GREATER_THAN&\
sort_column=cost&\
order=desc&\
page=0&\
per_page=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Success Response

Status Code: 200 OK

{
  "total_count": 150,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "call_sid": "CALL_abc123def456",
      "campaign_id": "550e8400-e29b-41d4-a716-446655440001",
      "ai_agent_id": "550e8400-e29b-41d4-a716-446655440002",
      "contact_id": "550e8400-e29b-41d4-a716-446655440003",
      "company_id": "550e8400-e29b-41d4-a716-446655440004",
      "call_from": "+1234567890",
      "call_to": "+9876543210",
      "call_duration": 125,
      "call_status": "completed",
      "call_direction": "outbound",
      "call_provider": "twilio_clusterlab",
      "call_rating": 5,
      "call_feedback": "Great conversation",
      "record_url": "https://recordings.example.com/call_123.mp3",
      "transcript": "Agent: Hello, how can I help you today?...",
      "is_test": false,
      "transcript_object": {
        "segments": [
          {"speaker": "agent", "text": "Hello, how can I help you today?", "timestamp": 0}
        ]
      },
      "transcript_language": "en-US",
      "cost": 0.85,
      "price_unit": "USD",
      "latency": 150,
      "disconnect_reason": "caller_hung_up",
      "analysis_sentiment": "positive",
      "agent_task_status": "completed",
      "agent_task_feedback": "Successfully handled customer inquiry",
      "metadata": {
        "custom_field": "value"
      },
      "agent_dynamic_variables": {
        "customer_name": "John Doe",
        "account_number": "12345"
      },
      "agent_post_call_outcomes": {
        "sale_made": true,
        "follow_up_required": false
      },
      "notes": "Customer interested in premium plan",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:32:00Z",
      "deleted_at": null,
      "started_at": "2024-01-15T10:30:15Z",
      "ended_at": "2024-01-15T10:32:20Z",
      "retry_at": null,
      "workspace_id": "production"
    }
  ]
}

Use Cases

1. Quality Assurance Review

Find all calls with poor ratings for review:

?filter_columns[]=call_rating&filter_values[]=3&filter_operator[]=LOWER_THAN&sort_column=call_rating&order=asc

2. Cost Analysis

Get expensive calls over $5:

?filter_columns[]=cost&filter_values[]=5.00&filter_operator[]=GREATER_THAN&sort_column=cost&order=desc

3. Failed Call Investigation

Find all failed outbound calls from today:

?filter_columns[]=call_status&filter_values[]=failed&filter_operator[]=EQUALS&filter_columns[]=call_direction&filter_values[]=outbound&filter_operator[]=EQUALS&start_date=2024-01-15

4. Transcript Search

Search for specific keywords in transcripts:

?filter_columns[]=transcript&filter_values[]=refund&filter_operator[]=CONTAINS

5. Performance Monitoring

Find calls with high latency:

?filter_columns[]=latency&filter_values[]=500&filter_operator[]=GREATER_THAN&sort_column=latency&order=desc

6. Test Call Exclusion

Get only production calls:

?filter_columns[]=is_test&filter_values[]=false&filter_operator[]=EQUALS

7. Sentiment Analysis

Find negative sentiment calls for training:

?filter_columns[]=analysis_sentiment&filter_values[]=negative&filter_operator[]=EQUALS

Notes

The search parameter searches across: call_to, notes, call_feedback, agent_task_feedback, and transcript
Excluded statuses: Calls with status scheduled or pstn-queued are automatically excluded from results
All text searches are case-insensitive
Date filters apply to the started_at field
When using multiple filters, they are combined with AND logic
The maximum per_page value should be reasonable (e.g., 100-500) to avoid performance issues

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

ai_agent_id

string<uuid>

Filter by AI agent ID

string

Search term for calls

status

string

Filter by call status

start_date

string<date>

Filter by start date (YYYY-MM-DD)

end_date

string<date>

Filter by end date (YYYY-MM-DD)

campaign_id

string<uuid>

Filter by campaign ID

sort_column

string

default:created_at

Column to sort by

order

string

default:desc

Sort order (asc/desc)

page

integer

default:0

Page number for pagination

per_page

integer

default:10

Number of items per page

filter_columns

string

Comma-separated list of columns to filter on

filter_values

string

Comma-separated list of values for the filter_columns

filter_operator

string

Operator for filtering (e.g., eq, neq, gt, lt)

workspace

string

default:default

Optional workspace filter. If not provided, it will fall back to use "default".

Response

Successfully retrieved calls

status

string

required

Status of the response, e.g., 'ok' or 'error'

message

string

required

A descriptive message for the response

data

object[] | null

The data payload, which is an array of call objects or an error string.

Show child attributes

API Documentation

Calls API

Phone Numbers

Company Users

Contacts

Campaigns

AI Agents

Workspaces

Webhooks

integrations

Modules

​Query Calls

​Endpoint Details

​Query Parameters

​Basic Filters

​Date Range Filters

​Pagination

​Sorting

​Supported Sort Columns

​Advanced Column Filtering

​Supported Filter Columns

Text Fields

Numeric Fields

Boolean Fields

UUID Fields

​Automatic Status Updates

​Example Requests

​Basic Query

​Filter by Campaign and Date Range

​Search with Status Filter

​Advanced Column Filtering - Multiple Conditions

​Complex Query Example

​Response

​Success Response

​Use Cases

​1. Quality Assurance Review

​2. Cost Analysis

​3. Failed Call Investigation

​4. Transcript Search

​5. Performance Monitoring

​6. Test Call Exclusion

​7. Sentiment Analysis

​Notes

Authorizations

Query Parameters

Response

Query Calls

Endpoint Details

Query Parameters

Basic Filters

Date Range Filters

Pagination

Sorting

Supported Sort Columns

Advanced Column Filtering

Supported Filter Columns

Automatic Status Updates

Example Requests

Basic Query

Filter by Campaign and Date Range

Search with Status Filter

Advanced Column Filtering - Multiple Conditions

Complex Query Example

Response

Success Response

Use Cases

1. Quality Assurance Review

2. Cost Analysis

3. Failed Call Investigation

4. Transcript Search

5. Performance Monitoring

6. Test Call Exclusion

7. Sentiment Analysis

Notes