Exporting agent stats with agent_stats_export

To feed a custom dashboard or a payroll spreadsheet, you want agent numbers as raw data, not as a screen you screenshot. The Non-Agent API function agent_stats_export exports agent activity statistics for any date-and-time range you ask for, one line per agent.

Required fields

• source - a short description (max 20 characters) of what made the call
• datetime_start - start of the window, in YYYY-MM-DD+HH:MM:SS format
• datetime_end - end of the window, same format

Note the plus sign between the date and time - that is how you encode the space in the URL. The source parameter here is also a required field, not just a label, so do not leave it off. There is more on that quirk in the source parameter guide.

Optional fields worth knowing

• agent_user - scope to a single agent (2 to 20 characters)
• campaign_id - scope to a single campaign (2 to 8 characters)
• time_format - H (1:23:45), HF (forced hour format, the default), M (minutes), or S (seconds)
• group_by_campaign - set YES to split each agent's activity onto separate lines per campaign
• stage and header - output format and an optional column-name header row

The api user needs user_level 7 or higher with "view reports" enabled.

A real example call

Here is a one-day export for a single agent, with times in minutes:

http://your-server/vicidial/non_agent_api.php?source=test&function=agent_stats_export&time_format=M&stage=pipe&user=6666&pass=1234&agent_user=6666&datetime_start=2012-08-09+00:00:00&datetime_end=2012-08-10+23:59:59

A successful call prints no SUCCESS line - just the rows. With header=YES you get the column names first; the data line packs in a lot:

user|full_name|user_group|calls|login_time|total_talk_time|avg_talk_time|avg_wait_time|pct_of_queue|pause_time|sessions|avg_session|pauses|avg_pause_time|pause_pct|pauses_per_session|wait_time|talk_time|dispo_time|dead_time

6666|Admin user|ADMIN|16|0:34:31|0:07:54|0:00:00|0:00:07|100%|1411|13|0:02:39|42|0:00:34|68.1%|3|0:01:44|0:07:54|0:01:22|0:00:00

That single row is most of an Agent performance report on its own: call count, login time, talk and wait times, pause time and pause percentage, sessions, and dead time. Divide talk time by login time and you have a rough Agent utilization figure straight out of the export. When group_by_campaign is on, campaign_id becomes the first column and each agent splits across the campaigns they were logged into.

How the export flows

sequenceDiagram
    participant R as Reporting client
    participant API as non_agent_api.php
    participant DB as Agent log tables
    participant CSV as Output stream
    R->>API: agent_stats_export + datetime range
    API->>API: check user_level >= 7
    API->>DB: aggregate per agent
    DB-->>API: talk/pause/session totals
    API->>CSV: format per time_format
    CSV-->>R: one line per agent

Errors and limits

A permission failure returns ERROR: agent_stats_export USER DOES NOT HAVE PERMISSION TO GET AGENT INFO - 6666|0. A bad range returns ERROR: agent_stats_export INVALID SEARCH PARAMETERS, and an empty window returns ERROR: agent_stats_export NO RECORDS FOUND. This function analyzes up to 10,000,000 records, so a wide date range across a big floor is fine - but expect it to take a moment. As with every Non-agent API call, check the first token before you trust the rest.

For a related how-to, see reading live call-status counts. And because every VICIfast box ships with full API (application programming interface) access, you can pipe these stats into your own BI tool without paying for an add-on - see the pricing page.