anchorIntroduction

This guide demonstrates how to migrate from the deprecated Queue Statistics and Agent Statistics REST APIs to the GraphQL Search API. Both legacy APIs will be end-of-life (EOL) on March 31, 2027.

The GraphQL Search API provides a more flexible and powerful way to retrieve contact center data, including queue and agent statistics, with better performance and filtering capabilities.

anchorAuthentication & Authorization

All three APIs require the same authentication:

• Required Scopes: cjp:config or cjp:config_read
• Required Roles: Administrator or Supervisor

anchorMigration Path

1. Queue Statistics API → GraphQL Search API

Legacy API: Get Queue Statistics

Endpoint: GET /v1/organization/{orgId}/queue-statistics

Parameters:

• from (required): Start time in epoch milliseconds
• to (required): End time in epoch milliseconds
• interval (required): Time interval (15, 30, or 60 minutes)
• queueIds (optional): Comma-separated list of queue IDs
• orgId (required): Organization ID

Example Request:

curl -X GET "https://api.wxcc-us1.cisco.com/v1/organization/{orgId}/queue-statistics?from=1629369769066&to=1629458280000&interval=30&queueIds=queue-id-1,queue-id-2" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response Data Includes:

• intervalStartTime: Start time of the interval
• totalOfferedTasks: Total tasks offered to the queue
• totalHandledTasks: Total tasks handled
• totalAbandonedTasks: Total tasks abandoned
• avgHandleTime: Average handle time
• avgSpeedToAnswer: Average speed to answer
• And more...

New API: GraphQL Search API for Queue Statistics

Endpoint: POST https://api.wxcc-us1.cisco.com/search

GraphQL Query for Queue Statistics:

query QueueStats($from: Long!, $to: Long!) {
  task(
    from: $from
    to: $to
    filter: {
      queueId: { in: ["queue-id-1", "queue-id-2"] }
    }
    aggregations: [
      { field: "id", type: count, name: "totalTasks" }
      { field: "connectedDuration", type: average, name: "avgHandleTime" }
      { field: "queueDuration", type: average, name: "avgQueueTime" }
      { field: "holdDuration", type: average, name: "avgHoldTime" }
      { field: "wrapupDuration", type: average, name: "avgWrapupTime" }
    ]
    aggregationInterval: {
      interval: THIRTY_MINUTES
    }
  ) {
    tasks {
      intervalStartTime
      lastQueue {
        id
        name
      }
      aggregation {
        name
        value
      }
    }
  }
}

Variables:

{
  "from": 1629369769066,
  "to": 1629458280000
}

Example Request:

curl -X POST "https://api.wxcc-us1.cisco.com/search" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -d '{
    "query": "query QueueStats($from: Long!, $to: Long!) { task(from: $from, to: $to, filter: { queueId: { in: [\"queue-id-1\", \"queue-id-2\"] } }, aggregations: [{ field: \"id\", type: count, name: \"totalTasks\" }, { field: \"connectedDuration\", type: average, name: \"avgHandleTime\" }, { field: \"queueDuration\", type: average, name: \"avgQueueTime\" }], aggregationInterval: { interval: THIRTY_MINUTES }) { tasks { intervalStartTime lastQueue { id name } aggregation { name value } } } }",
    "variables": {
      "from": 1629369769066,
      "to": 1629458280000
    }
  }'

Interval Mapping:

Available Interval Values:

• FIFTEEN_MINUTES - 15 minute intervals
• THIRTY_MINUTES - 30 minute intervals
• HOURLY - 1 hour intervals
• DAILY - Daily intervals
• WEEKLY - Weekly intervals
• MONTHLY - Monthly intervals

2. Agent Statistics API → GraphQL Search API

Legacy API: Get Agent Statistics

Endpoint: GET /v1/organization/{orgId}/agent-statistics

Parameters:

• from (required): Start time in epoch milliseconds
• to (required): End time in epoch milliseconds
• interval (required): Time interval (15, 30, or 60 minutes)
• agentIds (optional): Comma-separated list of agent IDs
• teamIds (optional): Comma-separated list of team IDs
• orgId (required): Organization ID

Example Request:

curl -X GET "https://api.wxcc-us1.cisco.com/v1/organization/{orgId}/agent-statistics?from=1629369769066&to=1629458280000&interval=30&agentIds=agent-id-1,agent-id-2" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

New API: GraphQL Search API for Agent Statistics

Endpoint: POST https://api.wxcc-us1.cisco.com/search

GraphQL Query for Agent Statistics:

query AgentStats($from: Long!, $to: Long!) {
  agentSession(
    from: $from
    to: $to
    filter: {
      agentId: { in: ["agent-id-1", "agent-id-2"] }
    }
    aggregations: [
      { field: "agentSessionId", type: count, name: "totalSessions" }
    ]
    aggregationInterval: {
      interval: THIRTY_MINUTES
    }
  ) {
    sessions {
      intervalStartTime
      agentId
      agentName
      teamName
      siteName
      aggregation {
        name
        value
      }
    }
  }
}

Variables:

{
  "from": 1629369769066,
  "to": 1629458280000
}

Example Request:

curl -X POST "https://api.wxcc-us1.cisco.com/search" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -d '{
    "query": "query AgentStats($from: Long!, $to: Long!) { agentSession(from: $from, to: $to, filter: { agentId: { in: [\"agent-id-1\", \"agent-id-2\"] } }, aggregations: [{ field: \"agentSessionId\", type: count, name: \"totalSessions\" }], aggregationInterval: { interval: THIRTY_MINUTES }) { sessions { intervalStartTime agentId agentName teamName aggregation { name value } } } }",
    "variables": {
      "from": 1629369769066,
      "to": 1629458280000
    }
  }'

anchorAvailable Aggregation Fields

Task (Queue Statistics) Fields

Common fields available for aggregation in task queries:

• id - Task identifier (use with count for total tasks)
• totalDuration - Total duration of the task
• connectedDuration - Time agent was connected with customer
• queueDuration - Time task spent in queue
• holdDuration - Time customer was on hold
• wrapupDuration - Time agent spent in wrap-up
• ringingDuration - Time task was ringing before agent answered
• consultDuration - Time spent in consultation
• conferenceDuration - Time spent in conference
• holdCount - Number of times customer was put on hold
• consultCount - Number of consultation requests
• conferenceCount - Number of conference calls
• transferCount - Number of transfers
• blindTransferCount - Number of blind transfers
• queueCount - Number of times task entered queue
• connectedCount - Number of tasks connected to agents

Agent Session Fields

Fields available for agent session queries:

• agentSessionId - Session identifier (use with count for total sessions)
• agentId - Agent identifier
• agentName - Agent name
• teamName - Team name
• siteName - Site name
• startTime - Session start time
• endTime - Session end time
• state - Agent state

Note: For detailed agent activity metrics (handle time, idle time, etc.), you'll need to query the task endpoint filtered by agent and aggregate the task-level metrics.

anchorAggregation Types

The GraphQL Search API supports the following aggregation types:

• count - Count of records
• sum - Sum of values
• average - Average of values
• max - Maximum value
• min - Minimum value
• cardinality - Count of unique values

anchorKey Differences and Advantages

GraphQL Search API Benefits

1. Flexible Queries: Request only the fields you need, reducing payload size
2. Advanced Filtering: Combine multiple filter conditions with complex logic
3. Custom Aggregations: Define your own aggregations with custom names
4. Response Compression: Enable gzip compression for responses > 1MB by including Accept-Encoding: gzip header
5. Unified Endpoint: Single endpoint for all contact center data queries
6. Better Performance: Optimized for large-scale data retrieval
7. More Interval Options: Support for daily, weekly, and monthly intervals

Important Notes

1. Time Range Limits:

   • from parameter cannot be older than 36 months from current time
   • to parameter, if set to future time, will be adjusted to current time
   • Duration between from and to must not exceed 365 days

2. Pagination: For large result sets, use the pagination parameter:

   task(from: $from, to: $to, pagination: { cursor: "0", limit: 100 }) {
     tasks { ... }
     pageInfo {
       hasNextPage
       endCursor
     }
   }
   

3. Response Compression: Include Accept-Encoding: gzip header to enable compression for responses exceeding 1MB

4. Aggregation Results: Results are returned in an aggregation array with name and value fields, where name matches the alias you specified in the query

anchorCode Examples

JavaScript/Node.js Example

import axios from 'axios';

async function getQueueStatistics(from, to, queueIds) {
  const query = `
    query QueueStats($from: Long!, $to: Long!) {
      task(
        from: $from
        to: $to
        filter: { queueId: { in: ${JSON.stringify(queueIds)} } }
        aggregations: [
          { field: "id", type: count, name: "totalTasks" }
          { field: "connectedDuration", type: average, name: "avgHandleTime" }
          { field: "queueDuration", type: average, name: "avgQueueTime" }
        ]
        aggregationInterval: { interval: THIRTY_MINUTES }
      ) {
        tasks {
          intervalStartTime
          lastQueue { id name }
          aggregation { name value }
        }
      }
    }
  `;

  const response = await axios.post(
    'https://api.wxcc-us1.cisco.com/search',
    {
      query,
      variables: { from, to }
    },
    {
      headers: {
        'Authorization': `Bearer ${process.env.WEBEX_TOKEN}`,
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Accept-Encoding': 'gzip'
      }
    }
  );

  return response.data;
}

// Usage
const stats = await getQueueStatistics(
  1629369769066,
  1629458280000,
  ['queue-id-1', 'queue-id-2']
);

// Process aggregation results
stats.data.task.tasks.forEach(task => {
  console.log(`Interval: ${new Date(task.intervalStartTime)}`);
  console.log(`Queue: ${task.lastQueue.name}`);
  
  task.aggregation.forEach(agg => {
    console.log(`${agg.name}: ${agg.value}`);
  });
});

Python Example

import requests
import json
from datetime import datetime

def get_agent_statistics(from_time, to_time, agent_ids, token):
    query = """
    query AgentStats($from: Long!, $to: Long!) {
      agentSession(
        from: $from
        to: $to
        filter: { agentId: { in: %s } }
        aggregations: [
          { field: "agentSessionId", type: count, name: "totalSessions" }
        ]
        aggregationInterval: { interval: THIRTY_MINUTES }
      ) {
        sessions {
          intervalStartTime
          agentId
          agentName
          teamName
          aggregation { name value }
        }
      }
    }
    """ % json.dumps(agent_ids)
    
    url = "https://api.wxcc-us1.cisco.com/search"
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Accept-Encoding': 'gzip'
    }
    
    payload = {
        'query': query,
        'variables': {
            'from': from_time,
            'to': to_time
        }
    }
    
    response = requests.post(url, headers=headers, json=payload)
    return response.json()

# Usage
stats = get_agent_statistics(
    1629369769066,
    1629458280000,
    ['agent-id-1', 'agent-id-2'],
    'your-token'
)

# Process results
for session in stats['data']['agentSession']['sessions']:
    print(f"Interval: {datetime.fromtimestamp(session['intervalStartTime']/1000)}")
    print(f"Agent: {session['agentName']}")
    
    for agg in session['aggregation']:
        print(f"{agg['name']}: {agg['value']}")

anchorMigration Checklist

• Review current usage of Queue Statistics and Agent Statistics APIs
• Identify all fields currently being used in your application
• Map legacy API fields to GraphQL Search API fields (see Available Aggregation Fields section)
• Update authentication and endpoint URLs
• Implement GraphQL queries with appropriate filters and aggregations
• Update interval values from integers (15, 30, 60) to ENUMs (FIFTEEN_MINUTES, THIRTY_MINUTES, HOURLY)
• Update response parsing to handle aggregation array structure
• Add response compression support (Accept-Encoding: gzip)
• Implement pagination for large result sets
• Test queries with your actual data
• Update error handling for GraphQL response format
• Deploy and monitor the new implementation
• Remove legacy API calls before March 31, 2027

anchorSupport and Resources

• GraphQL Search API Documentation: https://developer.webex.com/webex-contact-center/docs/api/v1/search
• Queue Statistics API (Legacy): https://developer.webex.com/webex-contact-center/docs/api/v1/queue-statistics/get-queue-statistics
• Agent Statistics API (Legacy): https://developer.webex.com/webex-contact-center/docs/api/v1/agents/get-agent-statistics

For questions or assistance with migration, please contact Webex Contact Center Developer Support.

Last Updated: March 2026