ai/docs/07-reference/02-ai-sdk-ui/32-prune-messages.mdx

AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.

---
title: pruneMessages
description: API Reference for pruneMessages.
---

# `pruneMessages()`

The `pruneMessages` function is used to prune or filter an array of `ModelMessage` objects. This is useful for reducing message context (to save tokens), removing intermediate reasoning, or trimming tool calls and empty messages before sending to an LLM.

```ts filename="app/api/chat/route.ts"
import { pruneMessages, streamText } from 'ai';
__PROVIDER_IMPORT__;

export async function POST(req: Request) {
  const { messages } = await req.json();

  const prunedMessages = pruneMessages({
    messages,
    reasoning: 'before-last-message',
    toolCalls: 'before-last-2-messages',
    emptyMessages: 'remove',
  });

  const result = streamText({
    model: __MODEL__,
    messages: prunedMessages,
  });

  return result.toUIMessageStreamResponse();
}
```

## Import

<Snippet text={`import { pruneMessages } from "ai"`} prompt={false} />

## API Signature

### Parameters

<PropertiesTable
  content={[
    {
      name: 'messages',
      type: 'ModelMessage[]',
      description: 'An array of ModelMessage objects to prune.',
    },
    {
      name: 'reasoning',
      type: `'all' | 'before-last-message' | 'none'`,
      description:
        'How to remove reasoning content from assistant messages. Default: "none".',
    },
    {
      name: 'toolCalls',
      type: `'all' | 'before-last-message' | 'before-last-\${number}-messages' | 'none' | Array<{ type: 'all' | 'before-last-message' | 'before-last-\${number}-messages'; tools?: string[] }>`,
      description:
        'How to prune tool call/results/approval content. Can specify a strategy string or an array for per-tool fine control. Default: [] (empty array, equivalent to "none").',
    },
    {
      name: 'emptyMessages',
      type: `'keep' | 'remove'`,
      description:
        'Whether to keep or remove messages whose content is empty after pruning. Default: "remove".',
    },
  ]}
/>

### Returns

An array of [`ModelMessage`](/docs/reference/ai-sdk-core/model-message) objects, pruned according to the provided options.

<PropertiesTable
  content={[
    {
      name: 'ModelMessage[]',
      type: 'Array',
      description: 'The pruned list of ModelMessage objects',
    },
  ]}
/>

## Example Usage

```ts
import { pruneMessages } from 'ai';

const pruned = pruneMessages({
  messages,
  reasoning: 'all', // Remove all reasoning parts
  toolCalls: 'before-last-message', // Remove tool calls except those in the last message
});
```

## Pruning Options

- **reasoning:** Removes reasoning parts from assistant messages. Use `'all'` to remove all, `'before-last-message'` to keep reasoning in the last message, or `'none'` to retain all reasoning.
- **toolCalls:** Prune tool-call, tool-result, and tool-approval chunks from assistant/tool messages. Default is an empty array (no pruning). Options include:
  - `'all'`: Prune all such content.
  - `'before-last-message'`: Prune except in the last message.
  - `'before-last-N-messages'`: Prune except in the last N messages.
  - `'none'`: Do not prune.
  - Or provide an array for per-tool fine control, e.g., `[{ type: 'before-last-message', tools: ['search', 'calculator'] }]` to prune only specific tools.
- **emptyMessages:** Set to `'remove'` (default) to exclude messages that have no content after pruning.

> **Tip**: `pruneMessages` is typically used prior to sending a context window to an LLM to reduce message/token count, especially after a series of tool-calls and approvals.

For advanced usage and the full list of possible message parts, see [`ModelMessage`](/docs/reference/ai-sdk-core/model-message) and [`pruneMessages` implementation](https://github.com/vercel/ai/blob/main/packages/ai/src/generate-text/prune-messages.ts).