> ## Documentation Index > Fetch the complete documentation index at: https://docs.unleashx.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```bash theme={null} 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. ```json theme={null} { "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` ```json theme={null} { "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` ```json theme={null} { "error": true, "code": 401, "message": "Invalid Auth Key or Session Expired", "data": {} } ``` ### 404 - Not Found **Status Code:** `404 Not Found` ```json theme={null} { "error": true, "code": 404, "message": "No call history found for the given filters", "data": {} } ``` ### 500 - Server Error **Status Code:** `500 Internal Server Error` ```json theme={null} { "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 ```bash theme={null} 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) ```bash theme={null} 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) ```bash theme={null} 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) ```bash theme={null} 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) ```bash theme={null} 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) ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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) ```bash theme={null} 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 ```bash theme={null} 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) ```bash theme={null} 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) ```bash theme={null} 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) ```bash theme={null} 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) ```bash theme={null} 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). ## Related Endpoints * `/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). *** ## OpenAPI ````yaml api-reference/openapi.json GET /agents/call-history openapi: 3.1.0 info: title: >- UnleashX - Build human like conversations | Voice Agents | Automations | AI Workforce version: 1.0.0 description: UnleashX - Your home for human like conversations servers: - url: https://www.tryunleashx.com/api/v1/global/ security: - bearerAuth: [] paths: /agents/call-history: get: tags: - Call Logs summary: Get agents call history (grouped by agent) parameters: - name: token in: header required: true description: API token for authentication schema: type: string - name: page in: query required: false schema: type: integer - name: limit in: query required: false schema: type: integer - name: fromdate in: query required: false schema: type: string - name: todate in: query required: false schema: type: string - name: agent_id in: query required: false schema: type: integer - name: calling_number in: query required: false schema: type: string - name: provider_number in: query required: false schema: type: string - name: status in: query required: false schema: type: string responses: '200': description: Agents call history retrieved successfully content: application/json: schema: type: object properties: datalist: type: array items: type: object properties: agent_id: type: integer agent_name: type: string total_calls: type: string success_calls: type: string failed_calls: type: string total_duration: type: string call_from: type: string nullable: true call_to: type: string nullable: true pagination: type: object properties: totalRecords: type: integer totalPages: type: integer currentPage: type: integer limit: type: integer total_calls: type: integer successful_calls: type: integer total_duration: type: string '400': description: Bad Request - Invalid parameters '401': description: Unauthorized '404': description: Not Found '500': description: Internal Server Error security: [] components: securitySchemes: bearerAuth: type: http scheme: bearer ````