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 oninteraction_started, half-open [from, to). Larger windows return 400 — 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_id returns 410.
  • 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

  1. Submit an export for the previous day via POST /multi-agent/governance/exports/conversations?from=…&to=…. The response returns 202 Accepted with an export_id.
  2. Poll GET /multi-agent/governance/exports/conversations/{export_id} every ~15s (at least once every 15 minutes) until it returns 200.
  3. 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

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)

ParameterTypeRequiredDefaultDescription
fromstring (ISO-8601 date-time)Yes—Start of the window, inclusive. Window is on interaction_started, half-open [from, to).
tostring (ISO-8601 date-time)Yes—End of the window, exclusive. Must be ≤ 30 days after from.
agent_idsarray of stringNo—Restrict to specific agent systems. Repeat the parameter for multiple values.
channelsarray of stringNo—Restrict to specific channels (e.g. voice, email). Repeat the parameter for multiple values.
exclude_cotbooleanNofalseWhen true, drop each turn's chain-of-thought and tool records, keeping only user-facing messages.

Response: 202 Accepted

{
  "export_id": "OPAQUE_EXPORT_ID",
  "status": "processing"
}

Error Responses

HTTP StatusError CodeDescription
400invalid_requestInvalid 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
429too_many_requestsRate limit exceeded — back off and retry
500export_failedThe export could not be submitted
503warehouse_unavailableTemporarily 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

ParameterTypeRequiredDescription
export_idstringYesThe opaque, account-bound identifier returned by the submit endpoint

Response: 202 Accepted (still processing)

{ "status": "processing" }

Response: 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:

HeaderDescription
Content-EncodingAlways gzip
Content-Typeapplication/x-ndjson
Content-Dispositionattachment; filename="conversations-export.ndjson.gz"

Error Responses

HTTP StatusError CodeDescription
400invalid_export_idThe 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
410export_expiredThe result has expired or the export_id is unknown — resubmit
429too_many_requestsRate limit exceeded — back off and retry
500export_failedThe 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

FieldTypeDescription
interaction_idstringIdentifier of the interaction. Present on every line — join to the Recordings API on this value.
account_idstringThe account that owns the interaction.
session_idstringSession associated with the interaction.
agent_idstringAgent system that handled the interaction.
agent_system_versionstringVersion of the agent system.
channelstringChannel (e.g. voice).
exitobjectHow the interaction ended (type, type_reason_code, context).
exit_typestringExit type (e.g. ok, escalate, error, abandoned).
interaction_started / interaction_endedstring (ISO-8601)Interaction start/end.
caller_id, user_profile_id, contact_person_idsstring / arrayIdentifiers associated with the interaction (may contain personal data).
source_systems, languages, directionsarray of stringInteraction metadata.
turnsarrayThe 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/result are 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).


Did this page help you?