> ## 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.

# Compact Trace

> Compress an agent trace to only the important details.

Relace Compact can process agent traces at **>50k tok/s**, enabling just-in-time compaction without interrupting the user experience.

## Input Formats

Send `messages` in any of the three standard API formats — the format is detected automatically:

| API Format Docs                                                                                   | Native endpoint        |
| :------------------------------------------------------------------------------------------------ | :--------------------- |
| [OpenAI Chat Completions](https://developers.openai.com/api/reference/chat-completions/overview/) | `/v1/chat/completions` |
| [OpenAI Responses](https://developers.openai.com/api/reference/resources/responses/)              | `/v1/responses`        |
| [Anthropic Messages](https://platform.claude.com/docs/en/api/messages)                            | `/v1/messages`         |

The compressed `messages` in the response come back in the same format you sent, and can replace your live message list directly.


## OpenAPI

````yaml POST /v1/code/compact
openapi: 3.0.1
info:
  title: Relace API
  description: API for accessing Relace code generation models.
  version: 1.0.0
  license:
    name: MIT
servers:
  - url: https://models.relace.ai
    description: Server for model API endpoints
  - url: https://api.relace.run
    description: Server for general infrastructure
security:
  - bearerAuth: []
paths:
  /v1/code/compact:
    post:
      description: Compress an agent trace to only the important details.
      requestBody:
        description: Agent trace to compact
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompactRequest'
            example:
              messages:
                - role: user
                  content: >-
                    Find where the rate limiter is configured and raise the
                    ceiling to 200 rps.
                - role: assistant
                  content: ''
                  tool_calls:
                    - id: call_abc123
                      type: function
                      function:
                        name: grep
                        arguments: '{"pattern": "rate_limit"}'
                - role: tool
                  tool_call_id: call_abc123
                  content: 'config/limits.py:14: RATE_LIMIT_RPS = 100'
                - role: assistant
                  content: >-
                    Found it — the ceiling is set in config/limits.py line 14.
                    Raising it to 200.
              target_tokens: 96000
              agent_model: gpt-5.5
      responses:
        '200':
          description: Compressed agent trace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompactResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '402':
          description: Out of credits, or no payment method on the account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error402'
        '404':
          description: Route not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '429':
          description: Rate limit exceeded, or the model is at capacity
          headers:
            Retry-After:
              schema:
                type: string
              description: Seconds to wait before retrying
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '502':
          description: Model server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error502'
        '503':
          description: Model temporarily unavailable
          headers:
            Retry-After:
              schema:
                type: string
              description: Seconds to wait before retrying
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error503'
        '504':
          description: Request to the model timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error504'
      servers:
        - url: https://models.relace.ai
components:
  schemas:
    CompactRequest:
      type: object
      required:
        - messages
      properties:
        messages:
          type: array
          description: >-
            The agent trace to compact, in OpenAI Chat Completions, OpenAI
            Responses, or Anthropic Messages format. The format is detected
            automatically, and the compressed trace is returned in the same
            format.
          items:
            type: object
            description: A message in the same format as the rest of the trace
        target_tokens:
          type: integer
          description: >-
            Approximate token budget for the retained context, in your agent
            model's tokens. Defaults to 96k tokens. Counts are computed with a
            heuristic lookup table to reduce API latency; your provider's count
            may differ slightly.
        agent_model:
          type: string
          description: >-
            The model that generated the trace, as its API model id (e.g.
            `claude-fable-5`, `gpt-5.5`, `grok-4.5`). Relace uses this to apply
            model-specific compaction improvements and count tokens more
            accurately.
    CompactResponse:
      type: object
      properties:
        messages:
          type: array
          description: The compressed agent trace, in the same format as the input.
          items:
            type: object
            description: A message in the same format as the input
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
              description: Number of tokens in the input conversation
            completion_tokens:
              type: integer
              description: Size of the retained view in the server's tokenizer
            total_tokens:
              type: integer
              description: Total number of tokens used
          description: >-
            Token usage information for the request, counted in the Relace
            Compact tokenizer.
      example:
        messages:
          - role: user
            content: >-
              Find where the rate limiter is configured and raise the ceiling to
              200 rps.
          - role: assistant
            content: >-
              Found it — the ceiling is set in config/limits.py line 14. Raising
              it to 200.
        usage:
          prompt_tokens: 135407
          completion_tokens: 17323
          total_tokens: 152730
    Error400:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: Invalid JSON in the request body.
    Error401:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: >-
            Invalid API key. Check the key, or create one at
            https://app.relace.ai.
    Error402:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: Out of credits. Add credits at https://app.relace.ai to continue.
    Error404:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: 'Route not found: POST /v1/code/rank'
    Error429:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: >-
            Rate limit exceeded. Retry after the Retry-After interval, or
            contact support to raise your limits.
    Error500:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: Internal server error.
    Error502:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: Model server error; retry shortly.
    Error503:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: Model 'relace-apply-3' is temporarily unavailable; retry shortly.
    Error504:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: Request to the model timed out after 60s.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Relace API key Authorization header using the Bearer scheme.

````