---
title: "Add an agent trace"
method: POST
path: "/trace/add"
tags: ["Traces"]
---

# Add an agent trace

`POST /trace/add`

Add an agent trace/transcript to the index.

Accepts traces as a string in Hyperdoc format (native), Vercel AI SDK format,
or OpenClaw JSONL format. The format is auto-detected if not specified.

**Hyperdoc format** (JSON array, snake_case with type discriminators):
```json
{"history": "[{\"type\": \"trace_message\", \"role\": \"user\", \"text\": \"Hello\"}]"}
```

**Vercel AI SDK format** (JSON array, camelCase):
```json
{"history": "[{\"role\": \"user\", \"content\": \"Hello\"}]"}
```

**OpenClaw JSONL format** (newline-delimited JSON):
```json
{"history": "{\"type\":\"session\",\"id\":\"abc\"}\n{\"type\":\"message\",\"message\":{\"role\":\"user\",...}}"}
```

## Request body

- TraceRequest — Request to add an agent trace.
  - `session_id` string — Resource identifier for the trace.
  - `history` string, required — The trace history as a string. Can be a JSON array of Hyperdoc steps, a JSON array of Vercel AI SDK steps, or OpenClaw JSONL.
  - `format` 'vercel' | 'hyperdoc' | 'openclaw', nullable — Trace format: 'vercel', 'hyperdoc', or 'openclaw'. Auto-detected if not set.
  - `title` string, nullable — Title of the trace
  - `metadata` object, nullable — Custom metadata for filtering. Keys must be alphanumeric with underscores, max 64 chars.
  - `date` string, date-time — Date of the trace
  - `extract` MemoryType[] — What kind of memories to extract from the trace

## Response `200`

Successful Response

- DocumentStatusResponse
  - `source` 'reddit' | 'notion' | 'slack' | 'google_calendar' | 'google_mail' | 'box' | 'dropbox' | 'github' | 'google_drive' | 'vault' | 'web_crawler' | 'trace' | 'microsoft_teams' | 'gmail_actions' | 'granola' | 'fathom' | 'fireflies' | 'linear' | 'hubspot' | 'salesforce' | 'coda' | 'lightfield' | 'gong', required
  - `resource_id` string, required
  - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped', required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/hyperspell/apis/hyperspell-api.md) · [All operations](https://skmtc.net/hyperspell/apis/hyperspell-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hyperspell/hyperspell-api/revisions/5721acd588e6/schema)