> ## Documentation Index
> Fetch the complete documentation index at: https://docs.relace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Compact agent traces to only the important details at >50k tok/s

## Overview

Models are now performing long horizon tasks that regularly hit 1m+ tokens. As the conversation prefix grows, cache read costs grow quadratically and eventually outweighs all other token costs.

Most information accumulated in agent traces doesn't need to be kept forever, and clearing it with regular compactions converts the cost of a trace from quadratic to linear. If you perform the compaction when the user is inactive for long enough to miss cache, you can also reduce the severity of cache write costs, as shown below.

<img className="block dark:hidden" src="https://mintcdn.com/relace/R2ku-kdD8J3PV8C9/images/compact_cache_costs_light.svg?fit=max&auto=format&n=R2ku-kdD8J3PV8C9&q=85&s=5cc307958a6c7a5d7c31c224d664bb07" alt="Tokens billed per turn and total cost, with and without compaction on cache miss" width="992" height="528" data-path="images/compact_cache_costs_light.svg" />

<img className="hidden dark:block" src="https://mintcdn.com/relace/R2ku-kdD8J3PV8C9/images/compact_cache_costs_dark.svg?fit=max&auto=format&n=R2ku-kdD8J3PV8C9&q=85&s=af5543bfdd372aa0c085a74d0377be92" alt="Tokens billed per turn and total cost, with and without compaction on cache miss" width="992" height="528" data-path="images/compact_cache_costs_dark.svg" />

<p style={{ textAlign: 'left', fontSize: '0.85em', opacity: 0.7 }}>
  Compacting on cache miss nearly halves the cost of a 50-turn trace. For best results, we recommend keeping the conversation as close to 128k tokens as possible.
</p>

For summary-based compactions that take 1-2 minutes, this strategy disrupts the user flow. By using Relace Compact, you get imperceptible compactions that finish within a couple of seconds.

## Prerequisites

* [Sign up](https://app.relace.ai) for a Relace account.
* Create an [API key](https://app.relace.ai/settings/api-keys).

<Steps>
  <Step title="Prepare Your Agent Trace">
    Construct `messages` exactly as your agent holds them for inference: OpenAI `v1/chat/completions`, OpenAI `v1/responses`, or Anthropic `v1/messages`. The format is detected automatically by the API and returned in the same format.
  </Step>

  <Step title="Call the Compact Endpoint">
    <CodeGroup>
      ```python Python theme={null}
      import requests

      response = requests.post(
          "https://compact.endpoint.relace.run/v1/code/compact",
          headers={"Authorization": "Bearer [YOUR_API_KEY]"},
          json={
              "messages": messages,
              "target_tokens": 25000,
              "agent_model": "claude-fable-5",
          },
      )
      result = response.json()
      ```

      ```typescript TypeScript theme={null}
      const response = await fetch("https://compact.endpoint.relace.run/v1/code/compact", {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${apiKey}`,
          "Content-Type": "application/json"
        },
        body: JSON.stringify({
          messages: messages,
          target_tokens: 25000,
          agent_model: "claude-fable-5"
        })
      });

      const result = await response.json();
      ```
    </CodeGroup>

    The parameter `target_tokens` sets the token budget for the retained context (defaults to 128k), and the optional `agent_model` tells us which model generated the trace so we can apply model-specific improvements and count tokens more accurately.
  </Step>

  <Step title="Use the Response">
    ```json theme={null}
    {
      "messages": [ ... ],
      "usage": {
        "prompt_tokens": 135407,
        "completion_tokens": 17323,
        "total_tokens": 152730
      }
    }
    ```

    The returned `messages` is the compressed trace, in the same format you sent. Tool ids come back verbatim, so it can replace your live message list directly.
  </Step>
</Steps>