Batch get AI summaries by resource IDs
/v1/ai/summaries/batchorg.permission.conversation.readorg.permission.customer.readThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Retrieves AI-generated summaries for multiple resources in a single request. Returns only summaries that exist; missing resource IDs are silently omitted.
This endpoint is useful for efficiently fetching summaries for a list of conversations, customers, or custom objects without making individual requests for each resource.
Summaries are automatically generated and updated based on each resource's content. For more information, see AI-generated summaries in the Kustomer Help Center.
Note: Either the AI Copilot or AI Summaries feature must be enabled in your subscription to use this endpoint. Requests return 403 Forbidden when neither feature is enabled.
AI summaries
An AI summary is a short, AI-written overview of a conversation, a customer or a custom object, which Kustomer generates and keeps up to date so agents can catch up without reading the whole history. The API reads these summaries, optionally translated.
Kustomer writes summaries automatically: when a conversation, customer or custom object (KObject) changes, Kustomer updates its summary, and agents see it in the agent desktop next to the record. Each summary belongs to exactly one record, so you look it up by that record's ID rather than by a summary ID. The API is read-only. You can't create, edit or delete a summary, or ask Kustomer to summarize something right now.
What a summary contains
| Field | Meaning |
|---|---|
resourceId |
The ID of the summarized conversation, customer or custom object. |
resourceType |
conversation, customer or kobject. |
text |
The summary itself. |
lastSummarizedAt |
When Kustomer last regenerated the text. Compare it with the record's own update time to see how current the summary is. |
createdAt, updatedAt |
When the summary record was created and last changed. |
A record that is new or hasn't been summarized yet has no summary: the single endpoint returns 404, and the batch endpoint leaves it out.
Translation
Pass lang, such as fr, es or de, to get text translated into that language, for example to show an English summary to a French-speaking team. If the translation fails, you get the summary in its original language instead of an error, so don't assume the text is in the language you asked for.
Which endpoint to use
| To | Call |
|---|---|
| Read the summary of one conversation, customer or custom object | GET /v1/ai/summaries/{resourceId} |
| Read summaries for many records at once | GET /v1/ai/summaries/batch, with up to 100 comma-separated IDs in resourceIds |
The batch endpoint returns only the summaries that exist, in a data array, so match each result to your records by attributes.resourceId rather than by position. IDs must be 24-character hexadecimal Kustomer IDs. A common pattern is to listen for conversation updates with a webhook, collect the IDs, and fetch their summaries in batches for a CRM, data warehouse or team digest. Summaries need the AI Copilot or AI Summaries feature on your plan; without either one, requests return 403 Forbidden. Reading a summary requires read access to conversations or customers.
Query parameters
Comma-separated list of resource IDs to fetch summaries for. Each ID must be a 24-character hex string. Maximum of 100 IDs per request. If omitted, the response contains an empty data array.
"507f1f77bcf86cd799439011,507f1f77bcf86cd799439012"Page number for pagination
1Example 1Number of items per page
100Example 100Target language code for translation (e.g. fr, es, de). When provided, summary text is translated to the specified language. Falls back to canonical summary text if translation fails.
"fr"Responses
OK