Call History

Retrieve a summarized call history grouped by agent. The endpoint returns one row per agent with totals (calls, successful calls, duration) and representative phone numbers for the agent’s calls.

API Endpoint

GET /api/v1/global/agents/call-history Content-Type: application/json Authentication: Required (API token validated by middleware apiauth.verifyToken). Provide token via header token or api_access_token.

Query Parameters / Request Body

This endpoint accepts parameters either as query parameters (GET) or as JSON in the request body (middleware maps req.data).

Parameter	Type	Required	Description
`page`	integer	No	Pagination page number. Defaults to env `DEFAULT_PAGE`.
`limit`	integer	No	Number of items per page. Defaults to env `DEFAULT_PAGE_LIMIT`.
`fromdate`	string	No	Start date for range (e.g. `2025-01-01` or datetime). Defaults to 1 month ago if omitted.
`todate`	string	No	End date for range. Defaults to now if omitted. (Code enforces a reasonable max window, ~3 months.)
`agent_id`	integer	No	Filter results to a specific agent.
`calling_number`	string	No	Partial match filter for calling number.
`provider_number`	string	No	Filter by provider number.
`status`	string/number	No	Filter by call/execution status (e.g. `completed`, `failed`).

Additional filters supported by the underlying summary/list endpoints may also be honored: sentiment, disposition, emotion, transcript, audio_url, etc. However this endpoint forces grouping by agent_id.

Available Filters (from code)

The controller and underlying agentController support a set of filters you can pass as query parameters or in the request body. Below are the most useful filters observed in the implementation:

Filter	Type	Description
`agent_id`	integer	Filter results to a specific agent (`AGENT_ID`).
`calling_number`	string	Partial-match filter against `CALLING_NUMBER` (uses SQL LIKE).
`provider_number`	string	Exact match against `PROVIDER_NUMBER`.
`status`	string/integer	Filters by execution `STATUS` in summary (and `CALL_STATUS` in per-call list endpoints). Common values: `completed`, `failed`, `running` (depends on your workspace data).
`fromdate` / `todate`	string	Date or datetime range. Controller defaults to last 1 month when omitted; code enforces a maximum reasonable window (~3 months).
`page`	integer	Pagination page.
`limit`	integer	Page size / limit.
`audio_url`	string	Pass `available` to return calls with an audio file (`FILE_PATH` is not null), or any other value to look for missing files.
`transcript`	string	Pass `available` to return calls with `TRANSCRIPT` present, or `unavailable` for missing transcripts.
`sentiment`	string	Filter by `OVERALL_SENTIMENT` recorded in the execution (if voice analysis ran).
`disposition`	string	Comma-separated dispositions; controller splits and applies `IN` filter on `DISPOSITION`.
`emotion`	string	Filter by `DETECTED_EMOTION`.
`input_data`	string	Partial-match (`LIKE`) against `INPUT_DATA`.
`cost_breakdown`	string	Partial-match (`LIKE`) against `COST_BREAKDOWN` or inside `RETURN_DATA`.
`duration`	string	For per-call list: expects a range like `min-max` to filter `TOTAL_DURATION`. (Used in `getAgentExecutionList`.)

Notes:

The getCallHistory endpoint specifically calls the summary function with group_by = 'agent_id', so grouping is enforced even if other group_by values exist in the summary helper.
Some filters have slightly different column names between the summary and the per-call list endpoints (STATUS vs CALL_STATUS); prefer using status for the summary endpoint and CALL_STATUS when calling the per-call list directly if you need exact behavior.
disposition accepts comma-separated values and will be converted into an IN filter in SQL.
For precise per-call data (transcripts, audio URLs, cost breakdown), use the per-call endpoint agentController.getAgentExecutionList and apply the same filters.

Example Request

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/call-history?page=1&limit=10&fromdate=2025-01-01&todate=2025-01-31" \
  -H "token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Successful Response (200)

Top-level response follows the project’s standard wrapper in many endpoints. The important data structure (simplified) is shown below.

{
  "datalist": [
    {
      "agent_id": 123,
      "agent_name": "Support Agent A",
      "total_calls": "12",
      "success_calls": "10",
      "failed_calls": "2",
      "total_duration": "3h:12m:5s",
      "call_from": "+14045551234",
      "call_to": "+919876543210"
    },
    {
      "agent_id": 456,
      "agent_name": "Sales Agent B",
      "total_calls": "8",
      "success_calls": "7",
      "failed_calls": "1",
      "total_duration": "1h:45m:0s",
      "call_from": "+14045559876",
      "call_to": "+919112223334"
    }
  ],
  "pagination": {
    "totalRecords": 2,
    "totalPages": 1,
    "currentPage": 1,
    "limit": 10
  },
  "total_calls": 20,
  "successful_calls": 17,
  "total_duration": "4h:57m:5s"
}

Response Fields

Field	Type	Description
`datalist`	array	Array of agent summary objects (one per agent).
`datalist[].agent_id`	integer	Agent ID (group value).
`datalist[].agent_name`	string	Agent display name (if available).
`datalist[].total_calls`	number	string	Total calls for that agent in the range.
`datalist[].success_calls`	number	string	Successful (completed) calls count.
`datalist[].failed_calls`	number	string	Failed calls count.
`datalist[].total_duration`	string	Formatted duration for that agent: `Xh:Ym:Zs`.
`datalist[].call_from`	string	null	Representative provider number (one sample per agent).
`datalist[].call_to`	string	null	Representative calling number (one sample per agent).
`pagination`	object	Pagination info: `totalRecords`, `totalPages`, `currentPage`, `limit`.
`total_calls`	integer	Overall total calls across returned agent groups.
`successful_calls`	integer	Overall successful calls across returned agent groups.
`total_duration`	string	Overall duration formatted `Xh:Ym:Zs`.

Error Responses

400 - Bad Request

Status Code: 400 Bad Request

{
  "error": true,
  "code": 400,
  "message": "Invalid date range or parameters",
  "data": {}
}

Common error messages:

Invalid date range or parameters
fromdate / todate format invalid

401 - Authentication Error

Status Code: 401 Unauthorized

{
  "error": true,
  "code": 401,
  "message": "Invalid Auth Key or Session Expired",
  "data": {}
}

404 - Not Found

Status Code: 404 Not Found

{
  "error": true,
  "code": 404,
  "message": "No call history found for the given filters",
  "data": {}
}

500 - Server Error

Status Code: 500 Internal Server Error

{
  "error": true,
  "code": 500,
  "message": "Internal server error",
  "data": {}
}

Pagination

Results are paginated. Use page and limit to page through results. Pagination metadata is returned in the pagination object. For large datasets, prefer narrow date ranges (≤ 3 months).

Important Notes

Grouping: This endpoint is implemented by calling getAgentExecutionSummary with group_by=agent_id, so responses are grouped by agent.
Representative numbers: call_from and call_to are taken from one representative execution (latest with non-null numbers) per agent — use getAgentExecutionList for full per-call records.
Date ranges: Defaults to last 1 month if fromdate/todate are not provided. The code enforces a reasonable maximum range (~3 months) for performance.
Pagination defaults: Values come from environment variables DEFAULT_PAGE and DEFAULT_PAGE_LIMIT if not provided.

Example: Use agent_id to fetch one agent’s summary

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/call-history?agent_id=123&fromdate=2025-01-01&todate=2025-01-31" \
  -H "token: YOUR_API_TOKEN"

Example Requests (filters)

Below are cURL examples that demonstrate how to call the endpoint using the various filters supported by the code. You can use GET query parameters or POST JSON bodies (middleware maps req.data).

1) Get summary for a specific agent (GET)

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/call-history?agent_id=123&fromdate=2025-01-01&todate=2025-01-31&page=1&limit=10" \
  -H "token: YOUR_API_TOKEN"

2) Get summary for a specific agent (POST)

curl -X POST "https://www.tryunleashx.com/api/v1/global/agents/call-history" \
  -H "Content-Type: application/json" \
  -H "token: YOUR_API_TOKEN" \
  -d '{ "agent_id": 123, "fromdate": "2025-01-01", "todate": "2025-01-31", "page": 1, "limit": 10 }'

3) Filter by calling_number (partial match)

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/call-history?calling_number=91234&page=1&limit=10" \
  -H "token: YOUR_API_TOKEN"

4) Filter by provider_number (exact match)

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/call-history?provider_number=+14045551234&page=1" \
  -H "token: YOUR_API_TOKEN"

5) Filter by status (e.g., completed)

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/call-history?status=completed&fromdate=2025-01-01&todate=2025-01-31" \
  -H "token: YOUR_API_TOKEN"

6) Filter for calls that have audio available

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/call-history?audio_url=available&fromdate=2025-01-01&todate=2025-01-31" \
  -H "token: YOUR_API_TOKEN"

7) Filter for calls with transcript available

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/call-history?transcript=available&fromdate=2025-01-01&todate=2025-01-31" \
  -H "token: YOUR_API_TOKEN"

8) Filter by sentiment or emotion

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/call-history?sentiment=positive&emotion=happy&fromdate=2025-01-01&todate=2025-01-31" \
  -H "token: YOUR_API_TOKEN"

9) Filter by disposition (comma-separated)

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/call-history?disposition=resolved,followup&fromdate=2025-01-01&todate=2025-01-31" \
  -H "token: YOUR_API_TOKEN"

10) Filter by input_data partial match

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/call-history?input_data=order&page=1" \
  -H "token: YOUR_API_TOKEN"

11) Filter by cost_breakdown (partial match)

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/call-history?cost_breakdown=google_tts&page=1" \
  -H "token: YOUR_API_TOKEN"

12) Duration range (per-call list; example for reference)

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/call-history?duration=30-300&page=1" \
  -H "token: YOUR_API_TOKEN"

13) Combined filters (example)

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/call-history?agent_id=123&calling_number=91234&status=completed&fromdate=2025-01-01&todate=2025-01-31&page=1&limit=20" \
  -H "token: YOUR_API_TOKEN"

14) POST example with multiple filters (combined)

curl -X POST "https://www.tryunleashx.com/api/v1/global/agents/call-history" \
  -H "Content-Type: application/json" \
  -H "token: YOUR_API_TOKEN" \
  -d '{
    "agent_id": 123,
    "calling_number": "91234",
    "status": "completed",
    "fromdate": "2025-01-01",
    "todate": "2025-01-31",
    "page": 1,
    "limit": 20
  }'

Notes:

Use GET for simple queries and POST when your client prefers JSON bodies or needs to send complex filters.
Some filters (like duration) are more relevant to the per-call list endpoint; the summary groups by agent but accepts the filter (the underlying query logic differs slightly).

/api/v1/global/agents/get — Get agent metadata and configuration.
/api/v1/global/agents/call — Initiate an agent call.
agentController.getAgentExecutionList — Use this endpoint for row-level per-call details (call-level list, transcripts, audio URLs).

Headers

token

string

required

API token for authentication

Query Parameters

page

integer

limit

integer

fromdate

string

todate

string

agent_id

integer

calling_number

string

provider_number

string

status

string

Response

Agents call history retrieved successfully

datalist

object[]

Show child attributes

pagination

object

Show child attributes

total_calls

integer

successful_calls

integer

total_duration

string

API Documentation

Phone Numbers

Voice AI

Call Logs

Campaigns

API Endpoint

Query Parameters / Request Body

Available Filters (from code)

Example Request

Successful Response (200)

Response Fields

Error Responses

400 - Bad Request

401 - Authentication Error

404 - Not Found

500 - Server Error

Important Notes

Example: Use agent_id to fetch one agent’s summary

Example Requests (filters)

1) Get summary for a specific agent (GET)

2) Get summary for a specific agent (POST)

3) Filter by calling_number (partial match)

4) Filter by provider_number (exact match)

5) Filter by status (e.g., completed)

6) Filter for calls that have audio available

7) Filter for calls with transcript available

8) Filter by sentiment or emotion

9) Filter by disposition (comma-separated)

10) Filter by input_data partial match

11) Filter by cost_breakdown (partial match)

12) Duration range (per-call list; example for reference)

13) Combined filters (example)

14) POST example with multiple filters (combined)

Headers

Query Parameters

Response

API Documentation

Phone Numbers

Voice AI

Call Logs

Campaigns

​API Endpoint

​Query Parameters / Request Body

​Available Filters (from code)

​Example Request

​Successful Response (200)

​Response Fields

​Error Responses

​400 - Bad Request

​401 - Authentication Error

​404 - Not Found

​500 - Server Error

​Pagination

​Important Notes

​Example: Use agent_id to fetch one agent’s summary

​Example Requests (filters)

​1) Get summary for a specific agent (GET)

​2) Get summary for a specific agent (POST)

​3) Filter by calling_number (partial match)

​4) Filter by provider_number (exact match)

​5) Filter by status (e.g., completed)

​6) Filter for calls that have audio available

​7) Filter for calls with transcript available

​8) Filter by sentiment or emotion

​9) Filter by disposition (comma-separated)

​10) Filter by input_data partial match

​11) Filter by cost_breakdown (partial match)

​12) Duration range (per-call list; example for reference)

​13) Combined filters (example)

​14) POST example with multiple filters (combined)

​Related Endpoints

Headers

Query Parameters

Response

API Endpoint

Query Parameters / Request Body

Available Filters (from code)

Example Request

Successful Response (200)

Response Fields

Error Responses

400 - Bad Request

401 - Authentication Error

404 - Not Found

500 - Server Error

Pagination

Important Notes

Example: Use agent_id to fetch one agent’s summary

Example Requests (filters)

1) Get summary for a specific agent (GET)

2) Get summary for a specific agent (POST)

3) Filter by calling_number (partial match)

4) Filter by provider_number (exact match)

5) Filter by status (e.g., completed)

6) Filter for calls that have audio available

7) Filter for calls with transcript available

8) Filter by sentiment or emotion

9) Filter by disposition (comma-separated)

10) Filter by input_data partial match

11) Filter by cost_breakdown (partial match)

12) Duration range (per-call list; example for reference)

13) Combined filters (example)

14) POST example with multiple filters (combined)

Related Endpoints