> ## 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.

# Query CCP logs

> Fetch raw Contact Control Panel (CCP) log entries captured by the Agent Experience Collector for one agent across a time window — to inspect agent-side errors, state transitions, and timing.

Returns raw Contact Control Panel (CCP) log entries that the Agent Experience Collector forwarded to Operata. Use it to inspect agent-side errors, softphone state transitions, and timing for a single agent across a time window.

## Endpoint

```http theme={null}
GET https://api.operata.io/v1/data/ccpLogs
```

## Parameters

### Query

| Name       | Type          | Required | Description                                                                                                                                    |
| ---------- | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `criteria` | string (JSON) | yes      | JSON object encoding the filter for this query. Url-encode the whole value. Supports `agent` (string), `fromTime` and `toTime` (ISO 8601 UTC). |

The `criteria` value is a JSON object passed as a single query-string parameter. For example, `{"agent":"agent_42","fromTime":"2026-05-18T00:00:00Z","toTime":"2026-05-18T01:00:00Z"}` becomes `criteria=%7B%22agent%22%3A%22agent_42%22%2C%22fromTime%22%3A%222026-05-18T00%3A00%3A00Z%22%2C%22toTime%22%3A%222026-05-18T01%3A00%3A00Z%22%7D`.

## Response

`200 OK` with an array of CCP log entries, ordered by `time`.

```json theme={null}
[
  {
    "agent": "agent_42",
    "component": "ccp",
    "exception": null,
    "level": "TRACE",
    "line": 0,
    "loggerId": "1747526402159-lbngq11trj",
    "objects": [
      { "nextToken": null, "permissions": ["outboundCall"] }
    ],
    "text": "AWSClient: <-- Operation 'getAgentPermissions' succeeded.",
    "time": "2026-05-18T00:01:02.577Z"
  }
]
```

| Field       | Type              | Description                                                               |
| ----------- | ----------------- | ------------------------------------------------------------------------- |
| `agent`     | string            | Agent username the log entry came from.                                   |
| `component` | string            | CCP subsystem that emitted the entry. Typical values: `ccp`, `softphone`. |
| `level`     | string            | Log level: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`.                     |
| `exception` | string \| null    | Stack or exception text when the entry is an error. `null` otherwise.     |
| `loggerId`  | string            | The CCP logger instance that emitted the entry.                           |
| `objects`   | array             | Structured payload the CCP attached to the entry, when present.           |
| `text`      | string            | Human-readable log message.                                               |
| `time`      | string (ISO 8601) | UTC timestamp the entry was emitted.                                      |

CCP log capture requires the Agent Experience Collector to be running in the agent's browser. Entries from a session in progress may not appear until that session ends.

## Example

<CodeGroup>
  ```bash curl theme={null}
  CRITERIA='{"agent":"agent_42","fromTime":"2026-05-18T00:00:00Z","toTime":"2026-05-18T01:00:00Z"}'
  curl -u "$OPERATA_GROUP_ID:$OPERATA_API_TOKEN" \
    --get "https://api.operata.io/v1/data/ccpLogs" \
    --data-urlencode "criteria=$CRITERIA"
  ```

  ```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 criteria = JSON.stringify({
    agent: "agent_42",
    fromTime: "2026-05-18T00:00:00Z",
    toTime: "2026-05-18T01:00:00Z",
  });

  const url = new URL("https://api.operata.io/v1/data/ccpLogs");
  url.searchParams.set("criteria", criteria);

  const response = await fetch(url, {
    headers: { Authorization: `Basic ${auth}` },
  });
  const entries = await response.json();
  ```

  ```python Python theme={null}
  import json, os, requests

  criteria = json.dumps({
      "agent": "agent_42",
      "fromTime": "2026-05-18T00:00:00Z",
      "toTime": "2026-05-18T01:00:00Z",
  })

  response = requests.get(
      "https://api.operata.io/v1/data/ccpLogs",
      auth=(os.environ["OPERATA_GROUP_ID"], os.environ["OPERATA_API_TOKEN"]),
      params={"criteria": criteria},
  )
  response.raise_for_status()
  entries = response.json()
  ```
</CodeGroup>

## Errors

| Status | Code              | When                                                                 | Recover                                                                        |
| ------ | ----------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| 400    | `invalid_request` | `criteria` is missing, not valid JSON, or references unknown fields. | Confirm the JSON parses and the field names are `agent`, `fromTime`, `toTime`. |

See [Errors](/docs/api-errors) for shared codes such as `401 unauthorized`, `429 rate_limited`, and the `5xx` family. For request caps see [Rate limits](/docs/api-rate-limits).

## Related

* [Get complete contact record](/docs/api-contact-record) — fetch the full Operata record for a contact ID surfaced in the logs.
* [CCP error logs](/docs/ccp-error-logs) — field reference for CCP error entries.
* [CCP agent states](/docs/ccp-agent-states) — agent state values referenced in log entries.
* [Errors](/docs/api-errors) — shared status codes and recovery patterns.


## OpenAPI

````yaml GET /v1/data/ccpLogs
openapi: 3.0.3
info:
  title: operata-api
  version: '1'
servers:
  - url: https://api.operata.io/
security:
  - sec0: []
paths:
  /v1/data/ccpLogs:
    get:
      summary: CCP Logs
      description: Query CCP logs
      operationId: ccp-logs
      parameters:
        - name: criteria
          in: query
          description: JSON input for agent name & time criteria
          schema:
            type: string
            format: json
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value: |-
                    [
                        {
                            "agent": "zoe",
                            "component": "ccp",
                            "exception": null,
                            "level": "TRACE",
                            "line": 0,
                            "loggerId": "1610928002159-lbngq11trj",
                            "objects": [
                                {
                                    "nextToken": null,
                                    "permissions": [
                                        "outboundCall"
                                    ]
                                }
                            ],
                            "text": "AWSClient: <-- Operation 'getAgentPermissions' succeeded.",
                            "time": "2021-01-18T00:01:02.577Z"
                        },
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
      deprecated: false
components:
  securitySchemes:
    sec0:
      type: http
      scheme: basic

````