Skip to main content
Retrieve per-call records (executions) for agents. This endpoint returns detailed call-level records (transcripts, audio paths, durations, dispositions, etc.) and supports multiple filters.

​
API Endpoint

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

​
Query Parameters

ParameterTypeRequiredDescription
agent_idintegerNoFilter records for a specific agent.
calling_numberstringNoPartial-match against CALLING_NUMBER (uses SQL LIKE).
provider_numberstringNoExact match against PROVIDER_NUMBER.
statusstring/integerNoFilter by execution STATUS (or CALL_STATUS in some places). Examples: completed, failed.
fromdatestringNoStart date (e.g. 2025-01-01 or datetime). Defaults to 1 month back if omitted.
todatestringNoEnd date. Defaults to now if omitted.
pageintegerNoPage number (used with limit to paginate results).
limitintegerNoPage size / limit.
audio_urlstringNoUse available to return records that have an audio file (FILE_PATH present).
transcriptstringNoUse available to return records that have TRANSCRIPT present.
sentimentstringNoFilter by OVERALL_SENTIMENT (if voice analysis available).
dispositionstringNoComma-separated dispositions; will be applied as SQL IN filter.
emotionstringNoFilter by DETECTED_EMOTION.
input_datastringNoPartial-match (LIKE) against INPUT_DATA.
cost_breakdownstringNoPartial-match (LIKE) against COST_BREAKDOWN or within RETURN_DATA.
durationstringNoRange filter (e.g., 30-300) for TOTAL_DURATION (per-call list).
Note: The handler accepts parameters from req.query (GET). The underlying implementation also supports similar filters for POST bodies in the agent controller, but this global route is exposed as GET.

​
Example Requests

​
Get executions for an agent (GET)

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

​
Filter by calling number (partial)

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/executions/list?agent_id=962&calling_number=91234&page=1&limit=20" \
  -H "token: YOUR_API_TOKEN"

​
Filter by audio availability and transcript

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/executions/list?agent_id=962&audio_url=available&transcript=available" \
  -H "token: YOUR_API_TOKEN"

​
Filter by disposition and sentiment

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/executions/list?agent_id=962&disposition=resolved,followup&sentiment=positive" \
  -H "token: YOUR_API_TOKEN"

​
Successful Response (200)

Returns an object with datalist containing call execution records. Each record includes many fields; the key fields are listed below. The controller formats durations and dates (e.g., total_duration as 1h:2m:3s, date, time). 
{
  "datalist": [
    {
      "ID": 98765,
      "AGENT_ID": 962,
      "agent_name": "Support Agent A",
      "CALLING_NUMBER": "+919876543210",
      "PROVIDER_NUMBER": "+14045551234",
      "STATUS": "completed",
      "CALL_STATUS": "completed",
      "TOTAL_DURATION": 185,                // raw seconds in DB (in code returned as TOTAL_DURATION but formatted)
      "total_duration": "3m:5s",            // formatted string added by controller
      "CREATED_AT": "2025-01-15T10:12:34Z",
      "date": "15 Jan, 2025",
      "time": "10:12",
      "TRANSCRIPT": "Customer said ...",
      "FILE_PATH": "https://storage.example.com/recordings/..",
      "DISPOSITION": "resolved",
      "SUMMARY": "Call summary text",
      "RETURN_DATA": { /* trimmed, filtered in response */ },
      "INPUT_DATA": { /* request metadata */ },
      "COST_BREAKDOWN": [ /* formatted cost items */ ],
      "VOICE_CALL_ANALYSIS": { /* optional analysis */ },
      "VOICE_QUALITY_FEEDBACK": 1,
      "workflow_name": "Support Flow",
      "workflow_type": "IVR"
    }
  ]
}

​
Field Notes

  • total_duration is formatted by the controller as Xh:Ym:Zs or Mm:Ss style for readability (the DB stores seconds).
  • RETURN_DATA is filtered to remove some internal fields; cost_breakdown may be moved into RETURN_DATA.cost_breakdown if present.
  • FILE_PATH is the URL to audio recording (if available).
  • TRANSCRIPT may be null or empty if speech-to-text was not produced.
  • VOICE_QUALITY_FEEDBACK is a numeric rating stored for voice analysis (e.g., upvote/downvote).
  • agent_name is provided via join with agent details when available.

​
Pagination

  • The endpoint accepts page and limit to paginate results. The controller applies limit and offset when querying.
  • Note: the current implementation returns only datalist (array) and does not include pagination metadata (totalRecords, totalPages) in the response. Use page and limit to page through results.

​
Error Responses

​
400 Bad Request

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

​
401 Unauthorized

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

​
500 Internal Server Error

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

​
Important Notes & Recommendations

  • Use narrow date ranges (≤ 3 months) for faster queries. The underlying controller defaults to 1 month if fromdate/todate are omitted.
  • For more aggregate/grouped metrics use /api/v1/global/agents/call-history (agent-level summary).
  • For export of conversational data (Excel), the system provides a separate endpoint (downloadConversationalData) which streams an XLSX.
  • If you need pagination metadata added to the response, we can update the controller to include totalRecords and totalPages.