Every conversation, flattened: bulk Genesys Cloud detail export with analytics jobs

Finance wants last month's inbound calls reconciled against the CRM. The IVR owner wants to know how many callers struggled to enter an account number after the menu change. The compliance team wants the verification outcome every flow wrote, for every conversation in a quarter. Each request sounds simple, and each runs straight into the shape of Genesys Cloud CX conversation data: deep, nested, spread across several APIs, and far too large to page through one screen at a time.

Conversation Detail – Conversation Detail Collector inside the app – was built for exactly this. Sign in with a read-only OAuth client, optionally tick one or more divisions, pick a start and end date and time in UTC, and press Collect. The server gathers every matching conversation as a complete analytics conversation detail record, enriches it, resolves IDs to names, and offers two downloads: a single-sheet Excel workbook with one row per conversation, and a JSON file holding every full nested record plus a meta summary.

Genesys Cloud offers two doors into the same conversation detail data. The query endpoint, POST /api/v2/analytics/conversations/details/query, is built for users who need the most up-to-date data and a response right now. The price of speed is documented: shorter intervals – seven days unfiltered, 32 days filtered – smaller pages, and an explicit note that it is not intended for bulk export workloads. Since December 2020 it accepts interval start dates up to 558 days in the past, and Genesys recommends the asynchronous jobs endpoint for historical queries.

The jobs endpoint, POST /api/v2/analytics/conversations/details/jobs, is designed for data-export integrations. You submit a query and receive a jobId, poll until the state is FULFILLED, then read the results through a cursor rather than numbered pages, with page sizes of up to 10,000. The trade-off is freshness: the data behind jobs can lag real time by hours to a full day. For a date-range export that is the right bargain, so Conversation Detail is built on jobs, and uses the query endpoint for one thing only – a one-record probe for totalHits that drives a determinate progress bar.

Genesys Cloud CX has a capable export path of its own, and we recommend it wherever it fits. The Interactions view can be filtered by queue, user, wrap-up code, direction, MOS and much more, with custom date ranges of up to 31 days, and exported to CSV or PDF on demand or on a schedule. With the Reporting > Custom Participant Attributes > View permission, the export can include custom participant attributes. Limits are documented: conversations under 24 hours old export at up to 10,000 per 12-hour period, and older ones at up to 1,000,000 per export.

Conversation Detail does not replace that. It answers a different brief: an arbitrary date range collected in one run, the full nested routing history of each conversation preserved in JSON, participant attributes merged into one column per key, and, optionally, the Architect flow variables and DTMF entry trail for each call, extracted from historical flow execution data. It is aimed at analysts building datasets, auditors and integration teams, rather than at day-to-day performance monitoring.

Every collection runs as a detached server-side job. The range is split into windows of at most seven days, each one an asynchronous analytics details job. The engine submits the job, polls every four seconds for up to about 15 minutes until it is FULFILLED, then cursor-pages the results 500 at a time. Because the jobs API streams by cursor there is no offset-paging cap; conversations are de-duplicated across window boundaries and counted against a 250,000-record safety cap per collection, beyond which the result is marked truncated.

Division scoping uses a server-side segmentFilters predicate on divisionId. If an org's job API rejects that dimension, the app falls back to an unfiltered job and applies a record-level filter on divisionIds regardless, so results are identical either way – the fallback simply scans more, which the Scanned tile makes visible. Live progress streams to the browser: submitting, Genesys preparing, scanning, harvesting, flow data, resolving names. Refresh, navigate away or lose the network and the page reattaches; only the Cancel button stops a run.

Rate limits are treated as a design input, not an error. Genesys documents that services impose their own limits and answer with HTTP 429 and a Retry-After header. Every call in a session rides an adaptive pacer that starts at roughly 4.5 requests per second, slows by half again on each 429, honours Retry-After with jitter, and eases back after sustained success. Tokens refresh proactively before expiry, so long runs never die halfway. Sizing guidance is published in the guide: around 10,000 conversations is of the order of 40 minutes of harvesting.

Two enrichment passes turn analytics records into business datasets. First, participant attributes – the key/value pairs your flows write with Set Participant Data, such as account numbers, intents and verification outcomes – are fetched once per kept conversation from the live conversation object, GET /api/v2/conversations/{conversationId}. Each participant keeps its own map, and a merged conversation-level map joins differing values with a pipe. A junk-key filter drops auto-written keys that embed GUIDs, so only human-named attributes become Excel columns. Conversations beyond the live API's retention are recorded as attributes not resolved; their analytics fields remain complete.

Second, and opt-in per run, the app reads Architect historical flow execution data. For each conversation that traversed a flow it queries the flow instances, batches them into download jobs and extracts every author-declared variable with its final value, plus each Collect Input and Menu step as a sequence of attempts. The result reads like a story: Account Number: ∅ → 703986 (2 tries, 1 failed). Variables are classified structurally by flow action type – caller input and assignments first, lookup outputs second – so the extraction adapts to any org's flows without guessing from names.

The limits are respected, not hidden. Flow data exists only where execution data storage was enabled when the call ran, and Genesys retains it for 10 days. An enrichment cache, namespaced per OAuth client, keeps each finished conversation's attributes and flow extraction, so overlapping re-runs are much faster and previously collected flow data outlives that window.

The Excel workbook is deliberately flat: one Conversations sheet, one row per conversation, a frozen bold header. Fixed columns come first – conversation ID, start and end in UTC, duration, direction, media types, participants and purposes, agent, queue, wrap-up, flow and division names alongside their IDs, customer ANI and DNIS, external contact IDs and whether attributes were resolved. Then come the IVR columns, one column per flow variable and one per participant-attribute key. Multiple values within a conversation join with commas, so a pivot table or BI import works first time.

Flattening always loses something, which is why the JSON download keeps every full nested record – participants, sessions, segments and metrics – plus a meta summary that carries totals, resolved name maps and the sorted attribute and variable column lists that downstream tooling needs. Guards protect both formats: the workbook is capped at 1,000,000 rows and 16,000 dynamic columns, and very large sources go to JSON. Finished collections stay downloadable and are owner-scoped to the OAuth client that created them; a Delete data button purges your own collections when a piece of work is done.

Conversation Detail was designed and proved the way we deliver for clients. Requirements came from real reconciliation and IVR-audit work; the design records why jobs beat queries for this brief; the engine has mock-fetch integration tests covering the job lifecycle, windowing, enrichment and the job registry; and negative paths – failed, cancelled or expired jobs, 422s on flow-data batches, permission gaps – each have a defined, logged outcome. The client is strictly read-only: every POST is a query or job submission, and nothing in the org is ever created, changed or deleted.

The app is part of the QVCCS App Suite included with every Managed Professional Services tier, and it pairs with Conversation Analyser: shortlist interesting conversation IDs here, then dissect each one there. When the dataset is the start of a bigger reporting or data-warehouse project, we muster the team from our own bench – Business Analysts to define the measures, a Solution Architect for the data model, Senior Developers for the pipelines – and take end-to-end ownership of the outcome.