Skip to main content
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).
ParameterTypeRequiredDescription
pageintegerNoPagination page number. Defaults to env DEFAULT_PAGE.
limitintegerNoNumber of items per page. Defaults to env DEFAULT_PAGE_LIMIT.
fromdatestringNoStart date for range (e.g. 2025-01-01 or datetime). Defaults to 1 month ago if omitted.
todatestringNoEnd date for range. Defaults to now if omitted. (Code enforces a reasonable max window, ~3 months.)
agent_idintegerNoFilter results to a specific agent.
calling_numberstringNoPartial match filter for calling number.
provider_numberstringNoFilter by provider number.
statusstring/numberNoFilter 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:
FilterTypeDescription
agent_idintegerFilter results to a specific agent (AGENT_ID).
calling_numberstringPartial-match filter against CALLING_NUMBER (uses SQL LIKE).
provider_numberstringExact match against PROVIDER_NUMBER.
statusstring/integerFilters by execution STATUS in summary (and CALL_STATUS in per-call list endpoints). Common values: completed, failed, running (depends on your workspace data).
fromdate / todatestringDate or datetime range. Controller defaults to last 1 month when omitted; code enforces a maximum reasonable window (~3 months).
pageintegerPagination page.
limitintegerPage size / limit.
audio_urlstringPass available to return calls with an audio file (FILE_PATH is not null), or any other value to look for missing files.
transcriptstringPass available to return calls with TRANSCRIPT present, or unavailable for missing transcripts.
sentimentstringFilter by OVERALL_SENTIMENT recorded in the execution (if voice analysis ran).
dispositionstringComma-separated dispositions; controller splits and applies IN filter on DISPOSITION.
emotionstringFilter by DETECTED_EMOTION.
input_datastringPartial-match (LIKE) against INPUT_DATA.
cost_breakdownstringPartial-match (LIKE) against COST_BREAKDOWN or inside RETURN_DATA.
durationstringFor 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

FieldTypeDescription
datalistarrayArray of agent summary objects (one per agent).
datalist[].agent_idintegerAgent ID (group value).
datalist[].agent_namestringAgent display name (if available).
datalist[].total_callsnumberstringTotal calls for that agent in the range.
datalist[].success_callsnumberstringSuccessful (completed) calls count.
datalist[].failed_callsnumberstringFailed calls count.
datalist[].total_durationstringFormatted duration for that agent: Xh:Ym:Zs.
datalist[].call_fromstringnullRepresentative provider number (one sample per agent).
datalist[].call_tostringnullRepresentative calling number (one sample per agent).
paginationobjectPagination info: totalRecords, totalPages, currentPage, limit.
total_callsintegerOverall total calls across returned agent groups.
successful_callsintegerOverall successful calls across returned agent groups.
total_durationstringOverall 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

  1. Grouping: This endpoint is implemented by calling getAgentExecutionSummary with group_by=agent_id, so responses are grouped by agent.
  2. 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.
  3. Date ranges: Defaults to last 1 month if fromdate/todate are not provided. The code enforces a reasonable maximum range (~3 months) for performance.
  4. 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).