# Queue Logs

## Historical queue logs

These read-only endpoints retrieve historical events from `queue_log` and the aggregated results shown by Status / Queue History. Both full and read-only API keys are accepted. Every request must select one exact tenant code or tenant name, including requests using a global key.

<table id="bkmrk-endpointresult-get-%2F"><thead><tr><th>Endpoint</th><th>Result</th></tr></thead><tbody><tr><td>`GET /queuelogs`</td><td>Queue History aggregation, including recording metadata.</td></tr><tr><td>`GET /queuelogs/history`</td><td>Alias for the same aggregation. Add `view=simple` for the Simple Queue History query.</td></tr><tr><td>`GET /queuelogs/raw`</td><td>Individual stored events, ordered by ascending log ID.</td></tr><tr><td>`GET /queuelogs/history/download`</td><td>Download aggregated history as CSV.</td></tr><tr><td>`GET /queuelogs/raw/download`</td><td>Download individual stored events as CSV.</td></tr></tbody></table>

Ordinary endpoints default to JSON. Add `format=csv` to download CSV instead. The download paths default to CSV. All forms apply the same filters and pagination.

### Filters

<table id="bkmrk-parametermeaning-ten"><thead><tr><th>Parameter</th><th>Meaning</th></tr></thead><tbody><tr><td>`tenant`</td><td>Required, exact tenant code or name. Wildcard and cross-tenant selection are rejected.</td></tr><tr><td>`start`, `end`</td><td>Inclusive event timestamps in PBX server time: `YYYY-MM-DD HH:MM:SS`. Defaults to the start of the day seven days ago through the end of today. The same time prefilter is used by the Queue History page, so events outside the interval do not contribute to a call's aggregate.</td></tr><tr><td>`queue_id`</td><td>Optional internal `qu_id`, not the dialable queue number. A queue outside the selected tenant returns 404.</td></tr><tr><td>`callid`, `agent`</td><td>Exact stored call or agent identifier. In history mode, agent filtering is applied after aggregating the call events.</td></tr><tr><td>`event`</td><td>Raw mode only. Exact event such as `ENTERQUEUE`, `CONNECT` or `ABANDON`.</td></tr><tr><td>`disposition`</td><td>History only. Exact aggregated English value, such as `ANSWERED`, `ABANDONED`, `TRANSFERRED` or `TIMEOUT`.</td></tr><tr><td>`view`</td><td>History only: `complete` (default) or `simple`. Simple mode omits recording metadata.</td></tr><tr><td>`limit`</td><td>Page size, 1–10000. Defaults to 100 for JSON and 1000 for CSV.</td></tr><tr><td>`offset`</td><td>Zero-based offset, default 0, maximum 10000000.</td></tr><tr><td>`after_id`</td><td>Raw mode only. Retrieve rows whose ID is greater than this value. Use `next_after_id` and `offset=0` for subsequent incremental pulls.</td></tr></tbody></table>

### Examples

```bash
# Aggregated Queue History, using the same SQL as the page
curl --get 'https://pbx.example.com/pbx/openapi.php/queuelogs' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'tenant=TENANT_CODE' \
  --data-urlencode 'queue_id=25' \
  --data-urlencode 'start=2026-11-01 00:00:00' \
  --data-urlencode 'end=2026-11-01 23:59:59'

# Download raw events as CSV
curl --get 'https://pbx.example.com/pbx/openapi.php/queuelogs/raw/download' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'tenant=TENANT_CODE' \
  --data-urlencode 'start=2026-11-01 00:00:00' \
  --data-urlencode 'end=2026-11-01 23:59:59' \
  --data-urlencode 'limit=10000' \
  --dump-header queue-log-headers.txt --output queue-log-events.csv

# Download the Queue History aggregation as CSV
curl --get 'https://pbx.example.com/pbx/openapi.php/queuelogs/history/download' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'tenant=TENANT_CODE' \
  --data-urlencode 'view=simple' \
  --output queue-history.csv
```

### Results and pagination

JSON responses contain `data`, `tenant_id`, `mode`, `view`, `start`, `end`, `limit`, `offset`, `has_more`, `next_offset` and `next_after_id`. Continue with `offset=next_offset` until `has_more` is false. Raw results additionally provide `next_after_id` when another page exists; use it with `after_id` and reset `offset` to 0.

CSV is also paginated. Check `X-Has-More` and continue using `X-Next-Offset`, or `X-Next-After-Id` for raw results. Each CSV page includes its header row. Downloading one page does not imply that every matching record was returned.

Raw rows contain `id`, `time`, `callid`, `queuename`, `agent`, `event` and `data1` through `data5`. CSV exports these database columns; it is not an Asterisk pipe-delimited log file. Only events belonging to an existing queue in the tenant can be attributed to that tenant. Raw mode includes `REALTIME` and `NONE` call IDs when their queue belongs to the selected tenant; aggregated history excludes them, matching the page.

History returns one row per queue/call with its time, queue name, caller number and name, disposition, hangup party, pause reason, agent and agent name, transfer destination, hold/call times, original position, call ID, queue ID and composite queue row ID. Complete mode adds the selected recording metadata ID, summary, transcript, sentiment score and emotional analysis. UI links and action-icon HTML are omitted. History is ordered by time descending, then queue ID and call ID descending.

Tenant privacy rules are preserved: inbound caller digits are masked in history; raw `data1` through `data5` become `[hidden]` if either inbound or outbound number privacy is enabled. Reads do not change queue logs or run transfer repair. Unsupported methods return 405; invalid filters return 400; missing or foreign queue IDs return 404.