Analytics Historical API

Overview

The Avaya Infinity™ Historical API gives you programmatic access to historical contact center data stored as structured datasets. Query agent performance, queue metrics, interaction records, workflow execution traces, and login/logout events. All results are paginated and filterable by time interval.

This API is designed for integrations that need to extract historical data for external reporting tools, analytics platforms, data warehouses, or compliance archives. Data is returned in a column-oriented format: each response includes a columnHeaders array that defines the schema, and a records array where each row is an ordered list of values corresponding to those headers.

Common use cases include:

• Operational reporting: Pull agent and queue performance metrics into a BI tool or dashboard for historical trend analysis.
• Workforce management: Extract login/logout and auxiliary status data to feed into scheduling and adherence systems.
• Compliance and audit: Retrieve interaction segment records and workflow traces for quality assurance or regulatory review.
• Data warehouse ingestion: Periodically pull all datasets into a data lake using cursor-based pagination to process large volumes efficiently.

The API uses standard REST conventions and OAuth 2.0 Bearer token authentication.

API Reference: Historical API Reference →

Before You Begin

Find Your Customer Subdomain

All Historical API requests are scoped to your Avaya Infinity™ tenant. Your subdomain appears in your Infinity portal URL:

https://core.avaya1234.ec.avayacloud.com/app/core-config-ui/

Your subdomain is: avaya1234

All API requests use this base URL pattern:

https://core.{customerId}.ec.avayacloud.com/api/analytics/v2/datasets/{datasetName}

Request API Credentials

Contact Avaya Support to request a client_id and client_secret for the Historical API. Once provisioned, use these credentials to obtain a Bearer token via the OAuth 2.0 client credentials flow.

Obtain an Access Token

curl -X POST \
  https://core.avaya1234.ec.avayacloud.com/auth/realms/avaya/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id={clientId}&client_secret={clientSecret}"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1...",
  "expires_in": 900,
  "token_type": "bearer"
}

Include the token in the Authorization header of every request:

Authorization: Bearer {access_token}

Note: Tokens expire after 900 seconds (15 minutes). Implement token refresh in any long-running data pipeline.

For full authentication details, see How to Authenticate with Avaya Infinity™ APIs.

Available Datasets

All data is accessed through a single endpoint by specifying the datasetName path parameter. The datasets available are:

Analytics Insights datasets: interactionSegments and workflowTrace require the Analytics Insights entitlement. Requests for these datasets without the entitlement return 403 Forbidden with the message: "This dataset requires the Analytics Insights entitlement." Contact your Avaya administrator to enable this feature.

Key Concepts

Column-Oriented Response Format

The Historical API does not return JSON objects with named fields. Instead, each response consists of two parallel arrays:

• columnHeaders: an ordered list of {name, type} objects defining the schema for this dataset and query
• records: an array of rows, where each row is an array of values in the same order as columnHeaders

To work with the data, zip the headers and values together:

const { columnHeaders, records } = response;

const rows = records.map(record =>
  Object.fromEntries(columnHeaders.map((col, i) => [col.name, record[i]]))
);
// rows[0] = { ROW_ID: "ff0f980b...", STARTTIME: "00:45", CHANNEL: "email", ... }

column_names = [col['name'] for col in response['columnHeaders']]
rows = [dict(zip(column_names, record)) for record in response['records']]
# rows[0] = {'ROW_ID': 'ff0f980b...', 'STARTTIME': '00:45', 'CHANNEL': 'email', ...}

All values in records are returned as strings, regardless of the type declared in columnHeaders. Cast numeric and datetime fields in your application after reading them.

The interval Parameter

The interval parameter is required on every request. It controls the time range of data returned and its format depends on datasetType.

Interval datasets (datasetType=interval, the default)

Use YYYYMMDDHHmm format. The mm component represents 15-minute intervals: 00, 15, 30, or 45. Non-standard minute values are silently accepted but may return empty results. Data is typically available for intervals at least 30 minutes in the past.

interval=starting:202502010415,ending:202502010445

Daily datasets (datasetType=daily)

Use YYYYMMDD format. Non-zero HHmm suffixes are silently accepted but may return empty results.

interval=starting:20250201,ending:20250225

Both starting and ending are optional individually; you can supply just one to query from a point forward or up to a point. Supplying neither returns a 400 Bad Request.

Cursor-Based Pagination

Results are paginated using opaque cursor tokens. The response includes a pagination object and a links object:

{
  "pagination": {
    "pageSize": 20,
    "prevPageToken": "",
    "nextPageToken": "MjAyNS0xMC0yN1QxOTow..."
  },
  "links": {
    "prev": "",
    "next": "/v2/datasets/agent?interval=...&nextPageToken=MjAyNS0xMC0yN1QxOTow..."
  }
}

Important pagination notes:

• Pagination is forward-only. prevPageToken and links.prev are reserved for future use and currently always return an empty string. Do not rely on them for backward navigation.
• When nextPageToken is an empty string, you are on the last page with no more records to fetch.
• The links.next URL may contain unicode-escaped ampersands (\u0026). Parse these correctly when constructing subsequent requests, or use the nextPageToken value directly in your own URL construction.

The filter Parameter

The optional filter parameter narrows results to rows matching a specific column value. Format: COLUMN_NAME:value or COLUMN_NAME:value* (wildcard suffix).

Known filterable columns (consistent across most datasets):

Important: Not all column names are valid filter keys. Using a column that is not supported as a filter key returns 400 Invalid filter column. For example, AGENT_NAME:John* is not valid. Contact Avaya Support to confirm the full list of filterable columns for a specific dataset.

The 202 Accepted Response

A 202 Accepted response means your request was valid but the data pipeline has not yet finished processing the requested interval. The response body will include columnHeaders (so you know the schema) but records will be empty. Retry after a short delay, typically a few minutes.

This commonly occurs when querying very recent intervals that are still being processed.

Request Parameters

Making Your First Request

Basic Request: Queue Data for a Single Interval

curl -X GET \
  "https://core.avaya1234.ec.avayacloud.com/api/analytics/v2/datasets/queue?interval=starting:202502010415,ending:202502010445" \
  -H "Authorization: Bearer {access_token}"

Request with Filter and Page Size

curl -X GET \
  "https://core.avaya1234.ec.avayacloud.com/api/analytics/v2/datasets/agent?interval=starting:20250201,ending:20250201&datasetType=daily&filter=CHANNEL:phone&pageSize=50" \
  -H "Authorization: Bearer {access_token}"

Node.js

async function getDataset(accessToken, customerId, datasetName, interval, options = {}) {
  const params = new URLSearchParams({ interval, ...options });
  const response = await fetch(
    `https://core.${customerId}.ec.avayacloud.com/api/analytics/v2/datasets/${datasetName}?${params}`,
    { headers: { Authorization: `Bearer ${accessToken}` } }
  );

  if (response.status === 202) {
    console.log('Data not yet available for this interval. Retry shortly.');
    return null;
  }
  if (!response.ok) {
    const error = await response.json();
    throw new Error(`${error.title}: ${error.detail}`);
  }
  return response.json();
}

// Usage
const data = await getDataset(accessToken, 'avaya1234', 'queue',
  'starting:202502010415,ending:202502010445');

Python

import requests

def get_dataset(access_token, customer_id, dataset_name, interval, **params):
    url = f'https://core.{customer_id}.ec.avayacloud.com/api/analytics/v2/datasets/{dataset_name}'
    response = requests.get(
        url,
        headers={'Authorization': f'Bearer {access_token}'},
        params={'interval': interval, **params}
    )
    if response.status_code == 202:
        print('Data not yet available. Retry shortly.')
        return None
    response.raise_for_status()
    return response.json()

# Usage
data = get_dataset(access_token, 'avaya1234', 'agent',
    'starting:20250201,ending:20250201', datasetType='daily', filter='CHANNEL:phone')

Response Structure

All successful responses share the same top-level structure:

{
  "columnHeaders": [
    { "name": "ROW_ID", "type": "string" },
    { "name": "STARTTIME", "type": "string" },
    { "name": "CHANNEL", "type": "string" }
  ],
  "records": [
    ["ff0f980b...", "00:45", "email"],
    ["f80f3d4d...", "00:45", "phone"]
  ],
  "pagination": {
    "pageSize": 20,
    "prevPageToken": "",
    "nextPageToken": "MjAyNS0xMC0yN1QxOTow..."
  },
  "links": {
    "prev": "",
    "next": "/v2/datasets/queue?interval=...&nextPageToken=MjAyNS0xMC0yN1QxOTow..."
  }
}

Common Fields Across Datasets

These fields appear in most or all datasets:

Dataset Reference

queue: Queue Performance Metrics

Interval-level performance metrics per queue and communication channel. Use for reporting on queue throughput, wait times, and abandonment rates.

agent: Agent Performance Metrics

Interval-level performance metrics per agent and communication channel. Use for individual agent reporting, productivity analysis, and time-in-state calculations.

agentAux: Agent Auxiliary Status

Interval-level aux status metrics per agent, broken down by status type. Use to analyse time agents spend in each not-ready state.

agentByQueue: Agent Performance by Queue

Agent performance metrics aggregated at the queue level. Use when you need to understand which agents handled work for each queue, rather than agent-level totals across all queues.

agentLoginSessions: Agent Login Sessions

Records each agent login session. Use for staffing analysis and shift-level reporting.

Note: The column schema for this dataset is not represented in the API reference examples. Contact Avaya Support or query the dataset and inspect the columnHeaders array for the full list of available fields.

agentLoginLogoutByQueue: Agent Login/Logout by Queue

Login and logout events recorded at the queue level. Use for queue-level staffing history.

cxAgentLoginLogout: CX Agent Login/Logout

Full login session records with duration broken down by agent status type. Use for adherence reporting and session-level compliance data.

interactionSegments: Interaction Segments (Analytics Insights required)

Segment-level detail for every interaction, including agent assignment, queue routing, timing, transfer details, and outcome. Each interaction may produce multiple segment rows (one per routing/handling step).

workflowTrace: Workflow Execution Trace (Analytics Insights required)

Step-by-step execution history for workflow sessions. Each row represents one history item (a single step execution) within a workflow session. Use for debugging workflow logic, auditing automated routing decisions, and measuring step-level performance.

workflow, mpccdr, transcript, clientSessions

These datasets follow the same column-oriented response format. The available columns vary by dataset. Query the endpoint and inspect the columnHeaders array in the response to discover the full schema for each. Contact Avaya Support for detailed field-level documentation.

Integration Patterns

Pattern 1: Full Pagination All Records for a Date Range

Iterate through all pages for a given interval using nextPageToken.

import requests

def get_all_records(access_token, customer_id, dataset_name, interval, **params):
    """Retrieve all records for a dataset and interval, handling pagination."""
    base_url = f'https://core.{customer_id}.ec.avayacloud.com/api/analytics/v2/datasets/{dataset_name}'
    headers = {'Authorization': f'Bearer {access_token}'}
    all_records = []
    column_headers = None
    next_page_token = None

    while True:
        query_params = {'interval': interval, **params}
        if next_page_token:
            query_params['nextPageToken'] = next_page_token

        response = requests.get(base_url, headers=headers, params=query_params)

        if response.status_code == 202:
            print('Data not yet available. Retry shortly.')
            break

        response.raise_for_status()
        data = response.json()

        if column_headers is None:
            column_headers = data['columnHeaders']

        all_records.extend(data['records'])

        next_page_token = data['pagination'].get('nextPageToken', '')
        if not next_page_token:
            break  # No more pages

    print(f'Retrieved {len(all_records)} records')
    return column_headers, all_records

# Usage
headers, records = get_all_records(
    access_token, 'avaya1234', 'agent',
    'starting:20250201,ending:20250201',
    datasetType='daily'
)
column_names = [col['name'] for col in headers]
rows = [dict(zip(column_names, record)) for record in records]

Pattern 2: Handling the 202 Accepted Response with Retry

Data for recent intervals may not yet be processed. Implement a retry with backoff.

async function getDatasetWithRetry(accessToken, customerId, datasetName, interval, maxRetries = 5) {
  const url = `https://core.${customerId}.ec.avayacloud.com/api/analytics/v2/datasets/${datasetName}`;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(`${url}?interval=${encodeURIComponent(interval)}`, {
      headers: { Authorization: `Bearer ${accessToken}` }
    });

    if (response.status === 200) {
      return response.json();
    }

    if (response.status === 202) {
      const delaySeconds = Math.pow(2, attempt) * 30; // 30s, 60s, 120s...
      console.log(`Data not yet available. Retrying in ${delaySeconds}s (attempt ${attempt + 1}/${maxRetries})`);
      await new Promise(r => setTimeout(r, delaySeconds * 1000));
      continue;
    }

    const error = await response.json();
    throw new Error(`${response.status}: ${error.title} — ${error.detail}`);
  }

  throw new Error('Max retries exceeded. Data may not be available for this interval.');
}

Pattern 3: Filtering by Channel and Agent

Combine filter with interval parameters to scope results.

# Agent data for phone channel only, for a specific date
curl -X GET \
  "https://core.avaya1234.ec.avayacloud.com/api/analytics/v2/datasets/agent?interval=starting:20250310,ending:20250310&datasetType=daily&filter=CHANNEL:phone" \
  -H "Authorization: Bearer {access_token}"

# Queue data filtered to a specific queue ID
curl -X GET \
  "https://core.avaya1234.ec.avayacloud.com/api/analytics/v2/datasets/queue?interval=starting:202503100800,ending:202503101700&filter=QUEUE_ID:003d0110243d0fd4d9c7f27dea" \
  -H "Authorization: Bearer {access_token}"

Common Scenarios

All Values in Records Are Strings

Even though columnHeaders declares types such as number and datetime, all values in records are returned as strings. Cast values in your application:

column_map = {col['name']: col['type'] for col in data['columnHeaders']}
column_names = list(column_map.keys())

for record in data['records']:
    row = {}
    for i, value in enumerate(record):
        col_name = column_names[i]
        col_type = column_map[col_name]
        if col_type == 'number' and value:
            row[col_name] = float(value)
        elif col_type == 'datetime' and value:
            row[col_name] = value  # parse with your preferred datetime library
        else:
            row[col_name] = value

Empty String vs. Null in Records

Some fields return an empty string "" rather than null when no value is present. For example, LOGOUT_TIME for a session that is still active. Treat empty strings as absent values when they appear in number or datetime typed columns.

Unicode-Escaped Ampersands in Pagination Links

The links.next URL may contain \u0026 in place of &. If you are using links.next directly for subsequent requests, ensure your HTTP client handles unicode escaping, or extract the nextPageToken from pagination.nextPageToken and construct your own URL instead.

Querying Data from the Analytics Insights Datasets Without Entitlement

If your account does not have the Analytics Insights entitlement and you request interactionSegments or workflowTrace, the API returns 403 Forbidden:

{
  "title": "Forbidden",
  "status": 403,
  "detail": "This dataset requires the Analytics Insights entitlement. Please contact your administrator to enable Analytics Insights for your account."
}

Contact your Avaya administrator to check or enable entitlements.

Error Reference

Where Next?

• Try the interactive API explorer: The Historical API Reference lets you query live datasets directly from your browser.
• Subscribe to real-time events: For live agent and interaction state changes rather than historical snapshots, use the Notification API.
• Get live queue metrics: For real-time queue occupancy and agent availability, use the Queue Metrics API.
• Review authentication: For a refresher on token management, see How to Authenticate with Avaya Infinity™ APIs.

Related Resources

• Historical API Reference
• Queue Metrics Guide
• Notification API Guide
• How to Authenticate with Avaya Infinity™ APIs
• Avaya Infinity™ Documentation Center