> ## Documentation Index
> Fetch the complete documentation index at: https://docs.operata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List contact summaries
> Query a time window and get a paginated list of contacts — each with headline agent, network, audio, and duration metrics — to drive exports, listings, or alerting.
Query a time window and get a page of contacts with summary metrics — agent, location, network performance, MOS, and contact duration. Use it to power listing views, scheduled exports, or threshold-based alerting before drilling into the full record per contact.
## Endpoint
```http theme={null}
GET https://api.operata.io/v1/data/calls
```
## Parameters
### Query
| Name | Type | Required | Description |
| ----------------- | ----------------- | -------- | -------------------------------------------------------------------------------------- |
| `fromTime` | string (ISO 8601) | yes | Inclusive lower bound. UTC. |
| `toTime` | string (ISO 8601) | yes | Exclusive upper bound. UTC. |
| `cursor` | string | no | Opaque pagination cursor. See [Pagination](/docs/api-pagination). |
| `size` | integer | no | Page size. 1–100. Default 50. See [Pagination](/docs/api-pagination). |
| `contactId` | string | no | Filter to a single Amazon Connect Contact ID. |
| `networkType` | string | no | Filter by network type, for example `wlan` or `ethernet`. |
| `agentCity` | string | no | Filter by the agent's geolocated city. |
| `agentStatus` | string | no | Filter by agent status during the contact: `Talk` or `Mute`. |
| `mosFrom` | number | no | Inclusive lower bound on average MOS. Send with `mosTo`. |
| `mosTo` | number | no | Inclusive upper bound on average MOS. Send with `mosFrom`. |
| `jitterFrom` | integer | no | Inclusive lower bound on average jitter in milliseconds. Send with `jitterTo`. |
| `jitterTo` | integer | no | Inclusive upper bound on average jitter in milliseconds. Send with `jitterFrom`. |
| `rttFrom` | integer | no | Inclusive lower bound on average round-trip time in milliseconds. Send with `rttTo`. |
| `rttTo` | integer | no | Inclusive upper bound on average round-trip time in milliseconds. Send with `rttFrom`. |
| `packetsLostFrom` | integer | no | Inclusive lower bound on packets lost. Send with `packetsLostTo`. |
| `packetsLostTo` | integer | no | Inclusive upper bound on packets lost. Send with `packetsLostFrom`. |
Range filters (`mos*`, `jitter*`, `rtt*`, `packetsLost*`) require both ends in the same request.
## Response
`200 OK` with a paginated envelope. Each entry in `data[]` summarizes one contact.
```json theme={null}
{
"data": [
{
"softphoneSummary": {
"contactId": "6347b169-063f-48f1-8d2e-001204be6677",
"agentUserName": "agent_42",
"agentCity": "Sydney",
"agentRegion": "New South Wales",
"agentCountry": "Australia",
"agentISP": "Google LLC",
"agentExternalIPAddress": "35.197.161.176",
"agentLocalIPAddress": "192.168.1.12",
"networkType": "wlan",
"protocol": "udp",
"port": 52500,
"networkPerformanceMetrics": {
"jitter": { "min": 1, "avg": 12, "max": 30 },
"rtt": { "min": 63, "avg": 75, "max": 77 },
"packetLoss": { "min": 0, "avg": 1, "max": 2 },
"mos": { "min": 4.27, "avg": 4.32, "max": 4.40 },
"totals": {
"bytesReceived": 447283,
"bytesSent": 480531,
"packetsLost": 0,
"packetsSent": 0,
"packetsReceived": 0
}
}
},
"operataBillingSummary": {
"agentInteractionDurationRoundedMin": 1,
"agentInteractionDurationActualSec": 16,
"operataStatsDurationRoundedMin": 2,
"operataStatsDurationSec": 103
},
"contactDurationSummary": {
"contactDurationRoundedMin": 1,
"contactDurationActualSec": 27
}
}
],
"next_cursor": "eyJvZmZzZXQiOjUwfQ=="
}
```
| Field | Type | Description |
| ----------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `data[].softphoneSummary` | object | Agent, location, network, and call-quality metrics captured by the Agent Experience Collector. |
| `data[].softphoneSummary.contactId` | string | Amazon Connect Contact ID. Pair with [Contact record](/docs/api-contact-record) or [Contact stats](/docs/api-contact-stats). |
| `data[].operataBillingSummary` | object | Durations Operata uses for billing rollups. |
| `data[].contactDurationSummary` | object | Total contact duration in seconds and rounded minutes. |
| `next_cursor` | string \| null | Cursor for the next page, or `null` at the end. See [Pagination](/docs/api-pagination). |
## Example
Fetch the first page of a 24-hour window, then advance to the next page using the returned cursor.
```bash curl theme={null}
# First page.
curl -u "$OPERATA_GROUP_ID:$OPERATA_API_TOKEN" \
"https://api.operata.io/v1/data/calls?fromTime=2026-05-17T00:00:00Z&toTime=2026-05-18T00:00:00Z&size=50"
# Next page — copy `next_cursor` from the previous response.
curl -u "$OPERATA_GROUP_ID:$OPERATA_API_TOKEN" \
"https://api.operata.io/v1/data/calls?cursor=eyJvZmZzZXQiOjUwfQ%3D%3D&size=50"
```
```javascript Node.js theme={null}
const groupId = process.env.OPERATA_GROUP_ID;
const apiToken = process.env.OPERATA_API_TOKEN;
const auth = Buffer.from(`${groupId}:${apiToken}`).toString("base64");
const url = new URL("https://api.operata.io/v1/data/calls");
url.searchParams.set("fromTime", "2026-05-17T00:00:00Z");
url.searchParams.set("toTime", "2026-05-18T00:00:00Z");
url.searchParams.set("size", "50");
const response = await fetch(url, {
headers: { Authorization: `Basic ${auth}` },
});
const { data, next_cursor: nextCursor } = await response.json();
```
```python Python theme={null}
import os, requests
response = requests.get(
"https://api.operata.io/v1/data/calls",
auth=(os.environ["OPERATA_GROUP_ID"], os.environ["OPERATA_API_TOKEN"]),
params={
"fromTime": "2026-05-17T00:00:00Z",
"toTime": "2026-05-18T00:00:00Z",
"size": 50,
},
)
response.raise_for_status()
body = response.json()
```
## Errors
| Status | Code | When | Recover |
| ------ | ---------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| 400 | `invalid_range` | `toTime` is missing, equal to, or before `fromTime`. | Send a window where `toTime` is strictly after `fromTime`. |
| 400 | `invalid_cursor` | The cursor is malformed or was issued by a different query. | Restart from the first page with the same filters. See [Pagination](/docs/api-pagination). |
| 404 | `not_found` | No contact summary records match the window or filters. | Widen the window or remove a filter. |
See [Errors](/docs/api-errors) for shared codes such as `401 unauthorized`, `429 rate_limited`, and the `5xx` family.
## OpenAPI
````yaml GET /v1/data/calls
openapi: 3.0.3
info:
title: operata-api
version: '1'
servers:
- url: https://api.operata.io/
security:
- sec0: []
paths:
/v1/data/calls:
get:
summary: Contact Summary
description: >-
Returns a list of calls made in a specified period & summary Operata
metrics
operationId: calls-list
parameters:
- name: size
in: query
description: Page size
schema:
type: string
default: none
- name: from
in: query
description: Record offset
schema:
type: string
default: none
- name: fromTime
in: query
description: From Time
schema:
type: string
default: none
- name: toTime
in: query
description: To Time
schema:
type: string
default: none
- name: networkType
in: query
description: Network Type
schema:
type: string
default: none
- name: contactId
in: query
description: Amazon Connect Contact ID
schema:
type: string
default: none
- name: agentCity
in: query
description: Agent City
schema:
type: string
default: none
- name: mosFrom
in: query
description: MOS From value (Both from and to values should present)
schema:
type: string
default: none
- name: mosTo
in: query
description: MOS To value (Both from and to values should present)
schema:
type: string
default: none
- name: jitterFrom
in: query
description: Jitter From value (Both from and to values should present)
schema:
type: string
default: none
- name: jitterTo
in: query
description: Jitter To value (Both from and to values should present)
schema:
type: string
default: none
- name: rttFrom
in: query
description: RTT From value (Both from and to values should present)
schema:
type: string
default: none
- name: rttTo
in: query
description: RTT To value (Both from and to values should present)
schema:
type: string
default: none
- name: packetsLostFrom
in: query
description: Packets Lost From value (Both from and to values should present)
schema:
type: string
default: none
- name: packetsLostTo
in: query
description: Packets Lost To value(Both from and to values should present)
schema:
type: string
default: none
- name: agentStatus
in: query
description: Agent Status (Talk/Mute)
schema:
type: string
default: none
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: |-
[
{
"softphoneSummary": {
"contactId": "6347b169-063f-48f1-8d2e-001204be6677",
"agentUserName": "gabriela",
"agentCity": "Sydney",
"agentRegion": "New South Wales",
"agentCountry": "Australia",
"agentISP": "Google LLC",
"agentExternalIPAddress": "35.197.161.176",
"agentLocalIPAddress": "192.168.1.12",
"networkType": "wlan",
"protocol": "udp",
"port": 52500,
"networkPerformanceMetrics": {
"jitter": {
"min": 1,
"avg": 73,
"max": 30
},
"rtt": {
"min": 63,
"avg": 75,
"max": 77
},
"packetLoss": {
"min": 0,
"avg": 1,
"max": 2
},
"mos": {
"min": 4.265032286010377,
"avg": 2.250246744910879,
"max": 4.400265513005151
},
"totals": {
"bytesReceived": 447283,
"bytesSent": 480531,
"packetsLost": 0,
"packetsSent": 0,
"packetsReceived": 0
}
}
},
"operataBillingSummary": {
"agentInteractionDurationRoundedMin": 1,
"agentInteractionDurationActualSec": 16,
"operataStatsDurationRoundedMin": 2,
"operataStatsDurationSec": 103
},
"contactDurationSummary": {
"contactDurationRoundedMin": 1,
"contactDurationActualSec": 27
}
}
]
schema:
type: array
items:
type: object
properties:
softphoneSummary:
type: object
properties:
contactId:
type: string
example: 6347b169-063f-48f1-8d2e-001204be6677
agentUserName:
type: string
example: gabriela
agentCity:
type: string
example: Sydney
agentRegion:
type: string
example: New South Wales
agentCountry:
type: string
example: Australia
agentISP:
type: string
example: Google LLC
agentExternalIPAddress:
type: string
example: 35.197.161.176
agentLocalIPAddress:
type: string
example: 192.168.1.12
networkType:
type: string
example: wlan
protocol:
type: string
example: udp
port:
type: integer
example: 52500
default: 0
networkPerformanceMetrics:
type: object
properties:
jitter:
type: object
properties:
min:
type: integer
example: 1
default: 0
avg:
type: integer
example: 73
default: 0
max:
type: integer
example: 30
default: 0
rtt:
type: object
properties:
min:
type: integer
example: 63
default: 0
avg:
type: integer
example: 75
default: 0
max:
type: integer
example: 77
default: 0
packetLoss:
type: object
properties:
min:
type: integer
example: 0
default: 0
avg:
type: integer
example: 1
default: 0
max:
type: integer
example: 2
default: 0
mos:
type: object
properties:
min:
type: number
example: 4.265032286010377
default: 0
avg:
type: number
example: 2.250246744910879
default: 0
max:
type: number
example: 4.400265513005151
default: 0
totals:
type: object
properties:
bytesReceived:
type: integer
example: 447283
default: 0
bytesSent:
type: integer
example: 480531
default: 0
packetsLost:
type: integer
example: 0
default: 0
packetsSent:
type: integer
example: 0
default: 0
packetsReceived:
type: integer
example: 0
default: 0
operataBillingSummary:
type: object
properties:
agentInteractionDurationRoundedMin:
type: integer
example: 1
default: 0
agentInteractionDurationActualSec:
type: integer
example: 16
default: 0
operataStatsDurationRoundedMin:
type: integer
example: 2
default: 0
operataStatsDurationSec:
type: integer
example: 103
default: 0
contactDurationSummary:
type: object
properties:
contactDurationRoundedMin:
type: integer
example: 1
default: 0
contactDurationActualSec:
type: integer
example: 27
default: 0
'401':
description: '401'
content:
text/plain:
examples:
Result:
value: "\n\n\n\t401 Authorization Required\n\n\n\n\t\n\t\t401 Authorization Required
\n\t\n\t
\n\tnginx/1.19.2\n\n\n"
'404':
description: '404'
content:
text/plain:
examples:
Result:
value: Call Summary record could not be found
deprecated: false
components:
securitySchemes:
sec0:
type: http
scheme: basic
````