AI Agent Governance Export API
Overview
The AI Agent Governance Export API allows customers to programmatically pull their Talkdesk AI Agent conversations in bulk — full interaction transcripts together with each turn's tool-call arguments and results — as a gzip-compressed NDJSON file. This API is part of AI Agent Platform.
Typical use cases include:
- Copying AI Agent conversation data into a customer's own storage for long-term retention (e.g., 180 days) and governance.
- Feeding QA sampling, analytics, and compliance pipelines from a single bulk source.
- Automating periodic (nightly/weekly) exports as part of a data-warehouse ingestion pipeline.
Because a single request can cover a large time range, the API is asynchronous: submit a time window, poll the returnedexport_id, then download the result.
Business Problem-Solving Context
What can I achieve with this API?
- Bulk-export conversations for a time window: Submit a window and receive an opaque
export_id. - Poll and download: Poll the
export_id; when ready, download a gzip NDJSON file with one interaction per line (transcript + per-turn tool-call arguments/results).
What business problems does this API solve?
- Long-term retention & governance: Retain agentic conversation data in your own storage beyond in-product windows, under a retention period you control.
- Bulk agentic detail without fan-out: Get transcripts and tool interactions in one pull instead of calling a per-interaction endpoint thousands of times.
- Automated pipelines: Integrate exports into nightly batch jobs that sync into your data warehouse.
What does this API support and what are its limitations?
- One export covers a window of up to 30 days on
interaction_started, half-open[from, to). Larger windows return400— split them. - Serves production interactions only (simulation interactions are excluded).
- Results are retained for roughly one hour after they're ready — download promptly; an expired/unknown
export_idreturns410. - The API does not push to your storage — you pull. Not a real-time stream.
- Call recordings are out of scope (use the Recordings API; join on
interaction_id).
Use Case
Nightly export into a data warehouse
- Submit an export for the previous day via
POST /multi-agent/governance/exports/conversations?from=…&to=…. The response returns202 Acceptedwith anexport_id. - Poll
GET /multi-agent/governance/exports/conversations/{export_id}every ~15s (at least once every 15 minutes) until it returns200. - Download the gzip NDJSON, decompress, and upsert each interaction (by
interaction_id) into your warehouse. Lines arrive in no guaranteed order.
Usage
The Conversations Export API provides two endpoints:
- POST /multi-agent/governance/exports/conversations — Submit a conversations export
- GET /multi-agent/governance/exports/conversations/{export_id} — Poll and download an export
POST /multi-agent/governance/exports/conversations
POST https://api.talkdeskapp.com/multi-agent/governance/exports/conversations
Starts an asynchronous export for the account and time window. Validates the window and returns 202 Accepted with an opaque, account-bound export_id. No conversation data is processed synchronously before the response is sent.
Request Parameters (query)
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
from | string (ISO-8601 date-time) | Yes | — | Start of the window, inclusive. Window is on interaction_started, half-open [from, to). |
to | string (ISO-8601 date-time) | Yes | — | End of the window, exclusive. Must be ≤ 30 days after from. |
agent_ids | array of string | No | — | Restrict to specific agent systems. Repeat the parameter for multiple values. |
channels | array of string | No | — | Restrict to specific channels (e.g. voice, email). Repeat the parameter for multiple values. |
exclude_cot | boolean | No | false | When true, drop each turn's chain-of-thought and tool records, keeping only user-facing messages. |
Response: 202 Accepted
202 Accepted{
"export_id": "OPAQUE_EXPORT_ID",
"status": "processing"
}Error Responses
| HTTP Status | Error Code | Description |
|---|---|---|
| 400 | invalid_request | Invalid or missing window, or window exceeds 30 days |
| 401 | — | Unauthorized — missing or invalid token |
| 403 | — | Forbidden — token missing the ai-agent-platform-agents:read scope |
| 429 | too_many_requests | Rate limit exceeded — back off and retry |
| 500 | export_failed | The export could not be submitted |
| 503 | warehouse_unavailable | Temporarily unavailable — retry after the Retry-After interval |
GET /multi-agent/governance/exports/conversations/{export_id}
GET https://api.talkdeskapp.com/multi-agent/governance/exports/conversations/{export_id}
Polls a previously submitted export. While processing, returns 202. When ready, returns 200 with a gzip-compressed NDJSON stream (one interaction per line). The export must belong to the authenticated account; another account's export_id returns 400.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
export_id | string | Yes | The opaque, account-bound identifier returned by the submit endpoint |
Response: 202 Accepted (still processing)
202 Accepted (still processing){ "status": "processing" }Response: 200 OK (ready)
200 OK (ready)A gzip-compressed NDJSON body — one interaction per line. Poll at least once every 15 minutes; download promptly (results retained ~1 hour).
Response Headers:
| Header | Description |
|---|---|
Content-Encoding | Always gzip |
Content-Type | application/x-ndjson |
Content-Disposition | attachment; filename="conversations-export.ndjson.gz" |
Error Responses
| HTTP Status | Error Code | Description |
|---|---|---|
| 400 | invalid_export_id | The export_id is invalid, forged, or issued for another account |
| 401 | — | Unauthorized — missing or invalid token |
| 403 | — | Forbidden — token missing the ai-agent-platform-agents:read scope |
| 410 | export_expired | The result has expired or the export_id is unknown — resubmit |
| 429 | too_many_requests | Rate limit exceeded — back off and retry |
| 500 | export_failed | The export failed to produce a result |
Response Format (NDJSON)
The download is gzip-compressed NDJSON: one JSON object per line, each a single interaction with its turns folded in. Lines arrive in no guaranteed order — upsert by interaction_id.
Interaction (top-level) fields
| Field | Type | Description |
|---|---|---|
interaction_id | string | Identifier of the interaction. Present on every line — join to the Recordings API on this value. |
account_id | string | The account that owns the interaction. |
session_id | string | Session associated with the interaction. |
agent_id | string | Agent system that handled the interaction. |
agent_system_version | string | Version of the agent system. |
channel | string | Channel (e.g. voice). |
exit | object | How the interaction ended (type, type_reason_code, context). |
exit_type | string | Exit type (e.g. ok, escalate, error, abandoned). |
interaction_started / interaction_ended | string (ISO-8601) | Interaction start/end. |
caller_id, user_profile_id, contact_person_ids | string / array | Identifiers associated with the interaction (may contain personal data). |
source_systems, languages, directions | array of string | Interaction metadata. |
turns | array | The interaction's turns, ordered by turn_start. |
Each turn contains timing fields (turn_start, turn_end, STT/synthesis timestamps), warnings, errors, and a records array. Each record has a recordType (MESSAGE, TOOL_CALL, TOOL_EXECUTION) and the matching payload (message text + endpoints; tool name/arguments; tool result). With exclude_cot=true the records array keeps only user-facing messages.
Note: within
records, field names are camelCase (e.g.recordType,toolCall,llmAction);arguments/resultare JSON-encoded strings. Full field-level schema is in the OpenAPI reference.
Example line
{"interaction_id":"ia-abc123","account_id":"ACCOUNT_ID","agent_id":"as-456","channel":"voice","interaction_started":"2026-01-01T10:00:00.000Z","interaction_ended":"2026-01-01T10:05:00.000Z","turns":[{"turn_id":"t-1","turn_start":"2026-01-01T10:00:01.000Z","turn_end":"2026-01-01T10:00:09.000Z","records":[{"recordType":"MESSAGE","message":{"from":"USER","to":"RESPOND","msg":"I'd like to check my order status."}}]}]}Authentication & Authorization
This API requires OAuth 2.0 authentication (Bearer token) using the client-credentials grant.
Scope:
ai-agent-platform-agents:read— required for both endpoints (submit and poll/download).
Subscription Limits
- Window ≤ 30 days per request.
- Submit (
POST): 5 burst / 1 per second, per account. - Poll/download (
GET): 20 burst / 10 per second, per user. - Result retained ~1 hour after ready.
Availability
Available from: 2026-10-15 (Early Access).
Updated 13 days ago