# Get AI summary by resource ID

> GET /v1/ai/summaries/{resourceId} · AI and automations API

Source: https://developer.kustomer.com/api/ai/get-ai-summary-by-resource-id

```http
GET https://{orgname}.api.kustomerapp.com/v1/ai/summaries/{resourceId}
Authorization: Bearer <API key>
```

## Authorization

Requires any one of these roles: `org.permission.conversation.read`, `org.permission.customer.read`; or legacy `org.user.conversation.read`, `org.user.customer.read`. The API key or user must hold at least one of them. Legacy roles predate permission sets and still work.

Retrieves the AI-generated summary for a specific resource (conversation, customer, or custom object) by its ID.

Summaries are automatically generated and updated based on the resource's content. For more information, see [AI-generated summaries](https://help.kustomer.com/en_us/ai-generated-summaries-HkklW4Rkl) 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.

## About 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}`](https://developer.kustomer.com/api/ai/get-ai-summary-by-resource-id) |
| Read summaries for many records at once | [`GET /v1/ai/summaries/batch`](https://developer.kustomer.com/api/ai/batch-get-ai-summaries-by-resource-ids), 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](https://developer.kustomer.com/docs/events/outbound-webhooks), 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.

Related: [AI and automations API](https://developer.kustomer.com/docs/ai/ai-api#summaries), [Conversations](https://developer.kustomer.com/api/core-resources#conversations), [Custom objects](https://developer.kustomer.com/docs/concepts/custom-objects)

### Recipes

#### 1. Add AI summaries to a customer's conversations in your CRM

Copy the summary of each of a customer's conversations into another system, such as a CRM or data warehouse, in as few calls as possible.

**Step 1.** [`GET /v1/customers/email={email}`](https://developer.kustomer.com/api/core-resources/get-customer-by-email.md). Find the customer. A `404` means there's no customer with that email.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/customers/email=$EMAIL" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
CUSTOMER_ID=$(kusty api GET "/v1/customers/email=$EMAIL" | jq -r .data.id)
```

**Step 2.** [`GET /v1/customers/{id}/conversations`](https://developer.kustomer.com/api/core-resources/get-conversations-by-customer.md). List the customer's conversations and collect their IDs.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/customers/$CUSTOMER_ID/conversations" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/customers/$CUSTOMER_ID/conversations --all | jq -r .data.id > conversation-ids.txt
```

**Step 3.** [`GET /v1/ai/summaries/batch`](https://developer.kustomer.com/api/ai/batch-get-ai-summaries-by-resource-ids.md). Fetch summaries for up to 100 IDs per request, comma-separated in `resourceIds`. Conversations without a summary are simply left out, so match each result to your record by `attributes.resourceId`, never by position. Store `lastSummarizedAt` with the text so you can tell later whether it's stale.

```bash title="cURL"
curl --get "https://api.kustomerapp.com/v1/ai/summaries/batch" \
  --data-urlencode "resourceIds=$CONVERSATION_IDS" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
split -l 100 conversation-ids.txt batch-
for f in batch-*; do
  kusty api GET /v1/ai/summaries/batch --query "resourceIds=$(paste -sd, "$f")" --all
done | jq -c '.data | {id: .attributes.resourceId, summary: .attributes.text, at: .attributes.lastSummarizedAt}'
```

> Summaries need the AI Copilot or AI Summaries feature on your plan; without either, both summary endpoints return `403`.

#### 2. Keep a copied summary fresh when a conversation changes

React to conversation updates by re-reading the summary only when Kustomer has regenerated it, instead of polling every record.

**Step 1.** Subscribe to conversation update events with an [outbound webhook](https://developer.kustomer.com/docs/events/outbound-webhooks) and collect the conversation IDs they carry. Many updates arrive in bursts, so de-duplicate the IDs and process them every few minutes.

**Step 2.** [`GET /v1/ai/summaries/{resourceId}`](https://developer.kustomer.com/api/ai/get-ai-summary-by-resource-id.md). Read each conversation's summary by the conversation's ID. If `lastSummarizedAt` is newer than the value you stored, save the new `text`; otherwise skip the write. A `404` means Kustomer hasn't summarized the conversation yet, so try again on its next update. For more than a handful of IDs, use the batch endpoint instead.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/ai/summaries/$CONVERSATION_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/ai/summaries/$CONVERSATION_ID \
  --fields attributes.lastSummarizedAt,attributes.text
```

#### 3. Show a customer summary in the reader's language

Give a team that works in another language the AI summary of a customer, translated on the fly, for example in a support tool or an escalation email.

**Step 1.** [`GET /v1/customers/email={email}`](https://developer.kustomer.com/api/core-resources/get-customer-by-email.md). Look up the customer to get their ID. Customer summaries are keyed by the customer ID, the same way conversation summaries are keyed by the conversation ID.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/customers/email=$EMAIL" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
CUSTOMER_ID=$(kusty api GET "/v1/customers/email=$EMAIL" | jq -r .data.id)
```

**Step 2.** [`GET /v1/ai/summaries/{resourceId}`](https://developer.kustomer.com/api/ai/get-ai-summary-by-resource-id.md). Ask for the summary with `lang`, such as `fr` or `de`. If translation fails you get the summary in its original language rather than an error, so if the language matters, check the text before you show it as translated.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/ai/summaries/$CUSTOMER_ID?lang=fr" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/ai/summaries/$CUSTOMER_ID --query lang=fr --fields attributes.text,attributes.resourceType
```

### Example object

A real record from [`GET /v1/ai/summaries/{resourceId}`](https://developer.kustomer.com/api/ai/get-ai-summary-by-resource-id.md):

```json
{
  "id": "507f1f77bcf86cd799439021",
  "type": "summary",
  "attributes": {
    "resourceId": "507f1f77bcf86cd799439011",
    "resourceType": "conversation",
    "text": "Customer inquired about order status and requested a refund. Agent confirmed the order was delayed and issued a full refund. Customer expressed satisfaction with the resolution.",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:35:00.000Z",
    "lastSummarizedAt": "2024-01-15T10:35:00.000Z"
  },
  "relationships": {
    "org": {
      "links": {
        "self": "/v1/orgs/507f1f77bcf86cd799439010"
      },
      "data": {
        "type": "org",
        "id": "507f1f77bcf86cd799439010"
      }
    }
  }
}
```

Fields:

- `id` (string): The summary's own ID. You don't need it: summaries are looked up by the summarized record's ID, `resourceId`.
- `type` (string): Resource type
- `attributes.resourceId` (string): The ID of the summarized conversation, customer or custom object, the same ID you pass in the path or in `resourceIds`. Match batch results on it, because missing summaries are left out.
- `attributes.resourceType` (string): `conversation`, `customer` or `kobject` (a custom object record). Tells you which API to call for the record itself.
- `attributes.text` (string): The summary. With `lang` it's translated, but if translation fails you get the original language without an error, so don't assume which language it's in.
- `attributes.createdAt` (string (date-time)): When Kustomer first summarized the record.
- `attributes.updatedAt` (string (date-time)): Last update timestamp
- `attributes.lastSummarizedAt` (string (date-time)): When Kustomer last regenerated `text`. Compare it with the record's own `updatedAt` to see whether the summary covers the latest activity.

### Permissions

Fewest roles for a read-only integration: `org.permission.conversation.read`. For every endpoint: `org.permission.conversation.read`.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `resourceId` | string | yes | The ID of the resource (conversation, customer, or custom object) to retrieve the summary for |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `lang` | string | no | Target language code for translation (e.g. `fr`, `es`, `de`). When provided, the summary text is translated to the specified language. Falls back to the canonical summary if translation fails. |

## Responses

### 200

OK

- `data` (object)
  - `id` (string): Unique summary identifier
  - `type` (string): Resource type
  - `attributes` (object)
    - `resourceId` (string): ID of the summarized resource (conversation, customer, or custom object)
    - `resourceType` (string): Type of the summarized resource One of: `conversation`, `customer`, `kobject`.
    - `text` (string): AI-generated summary text
    - `createdAt` (string<date-time>): Creation timestamp
    - `updatedAt` (string<date-time>): Last update timestamp
    - `lastSummarizedAt` (string<date-time>): Timestamp of the most recent summarization
  - `relationships` (object)
    - `org` (object)

```json
{
  "data": {
    "id": "507f1f77bcf86cd799439021",
    "type": "summary",
    "attributes": {
      "resourceId": "507f1f77bcf86cd799439011",
      "resourceType": "conversation",
      "text": "Customer inquired about order status and requested a refund. Agent confirmed the order was delayed and issued a full refund. Customer expressed satisfaction with the resolution.",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:35:00.000Z",
      "lastSummarizedAt": "2024-01-15T10:35:00.000Z"
    },
    "relationships": {
      "org": {
        "links": {
          "self": "/v1/orgs/507f1f77bcf86cd799439010"
        },
        "data": {
          "type": "org",
          "id": "507f1f77bcf86cd799439010"
        }
      }
    }
  }
}
```

### 401

Unauthorized - Authentication required or invalid token

### 403

Forbidden - Insufficient permissions or AI Agents feature not enabled

### 404

Not Found - Resource does not exist

## Example request

```bash
curl --request GET \
  --url 'https://api.kustomerapp.com/v1/ai/summaries/507f1f77bcf86cd799439011' \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```