Stats API

This endpoint is the core of the uContact statistics system. It allows obtaining historical and aggregated data on agent and campaign performance. It is configurable through parameters to group, filter, and customize the returned metrics.

• Method: POST
• URL: https://<domain>.ucontactcloud.com/api/stats

General Description

The endpoint queries a telemetry database (ccrepo) to retrieve metrics. The request is made via POST, sending the configuration parameters in the URL (Query Params) and the resource filters (agents or campaigns) in the request body (Request Body).

Query Params

These are the parameters sent in the URL.

Required Parameters

Parameter	Type	Description	Example
type	String	The type of resource for which you want to obtain statistics.	agent, campaign
initialdate	String	The start date and time of the query range, including the time zone. The format must be "YYYY-MM-DD HH:mm:ss TimeZone".	2025-09-01 00:00:00 America/Chicago
finaldate	String	The end date and time of the query range, including the time zone. Same format as initialdate.	2025-09-07 23:59:59 America/Chicago
groupnum	String	Defines the grouping interval. It can be a number in minutes or a predefined string.	Numeric: 15, 30, 60<br>Text: mth (month), bim (bimonthly), tri (trimester), sem (semester), yer (year)
channels	String	Comma-separated list of channels. It is only required if type is campaign.	telephony,sms,email,whatsapp,messenger,instagram

Optional Parameters

Parameter	Type	Description	Example
metrics	String	A comma-separated list of the specific metrics you want to obtain. If not sent, all default metrics are returned. The list of metrics can be found here: campaigns and agents.	connected,inboundAnswered
byResource	Boolean	If true, the results will be grouped by each individual resource (e.g., a row will be returned for each agent). The default is false.	true
byChannel	Boolean	If true, the results will be grouped by channel. Mainly useful when type is campaign. The default is false.	true

Request Body

The body of the request is used to specify the exact resources to be queried.

• Content-Type: application/json
• Body: A JSON object containing a stats key. The value of stats is a string with comma-separated resource identifiers.

To filter users

{
   "stats": "Agent1,Agent2,Agent3"
}

To filter campaigns

{
   "stats": "Sales,Support"
}

Response Codes

• 200 OK: The request was successful, and the response contains the data.
• 400 Bad Request: Required parameters are missing or have an incorrect format.
• 408 Request Timeout: The database query took too long to execute.
• 500 Internal Server Error: An unexpected error occurred on the server.

Usage Examples

Agent statistics by resource

Get specific metrics for agents Agent1, Agent2, and Agent3 for a specific day, grouped hourly and broken down by each agent.

URL

/api/stats
?type=agent
&initialdate=2025-09-08 00:00:00 America/Mexico_City
&finaldate=2025-09-08 23:59:59 America/Mexico_City
&groupnum=60
&metrics=inInteractions,outInteractions,connected
&byResource=true

Body

{
   "stats": "Agent1,Agent2,Agent3"
}

Example Response

[
    {
        "date": "Sep 8, 2025, 9:00:00 AM",
        "resource": "Agent1",
        "inInteractions": 10,
        "outInteractions": 5,
        "connected": 3540
    },
    {
        "date": "Sep 8, 2025, 9:00:00 AM",
        "resource": "Agent2",
        "inInteractions": 12,
        "outInteractions": 3,
        "connected": 3480
    },
    {
        "date": "Sep 8, 2025, 9:00:00 AM",
        "resource": "Agent3",
        "inInteractions": 4,
        "outInteractions": 3,
        "connected": 3440
    },
    {
        "date": "Sep 8, 2025, 10:00:00 AM",
        "resource": "Agent1",
        "inInteractions": 8,
        "outInteractions": 6,
        "connected": 3510
    },
    {
        "date": "Sep 8, 2025, 10:00:00 AM",
        "resource": "Agent2",
        "inInteractions": 15,
        "outInteractions": 2,
        "connected": 3550
    },
    {
        "date": "Sep 8, 2025, 10:00:00 AM",
        "resource": "Agent3",
        "inInteractions": 9,
        "outInteractions": 4,
        "connected": 3490
    }
]

Specific campaign metrics by channel

Get only the inbound and outbound interaction count metrics for the Sales campaign on the telephony and whatsapp channels, with the results broken down by channel.

URL

/api/stats
?type=campaign
&initialdate=2025-09-01 00:00:00 UTC
&finaldate=2025-09-30 23:59:59 UTC
&groupnum=mth
&channels=telephony,whatsapp
&metrics=inInteractions,outInteractions
&byChannel=true

Body

{
   "stats": "Sales"
}

Example Response

[
    {
        "date": "Sep 1, 2025, 12:00:00 AM",
        "resource": "Sales",
        "channel": "telephony",
        "inInteractions": 1500,
        "outInteractions": 350
    },
    {
        "date": "Sep 1, 2025, 12:00:00 AM",
        "resource": "Sales",
        "channel": "whatsapp",
        "inInteractions": 2200,
        "outInteractions": 150
    }
]