history

GET

/v1/history

const url = 'https://example.com/v1/history?outcome=approved&type=text&has=attachments&kind=command';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://example.com/v1/history?outcome=approved&type=text&has=attachments&kind=command'

Resolved requests, newest resolution first, with cursor pagination. history.keep_days/max_requests and best-effort history.max_bytes bound retained requests; history.files_keep_days can expire files while keeping history.

Parameters

Query Parameters

cursor

string

Next_cursor of the previous page

limit

integer

Page size, default 50, maximum 500

outcome

How a resolved request ended, as history shows it. auto is a rule or YOLO-mode decision; expired includes timeouts that auto-approved (on_timeout: approve).

string

Allowed values: approved denied expired cancelled auto

Approved, denied, expired, cancelled, or auto (rule or YOLO decision)

agent

string

type

string

Allowed values: text markdown code diff files command json html image video audio file pdf email

Only requests with a preview of this type

has

Grouped history preview filter.

string

Allowed values: attachments

Attachments: any file, files, image, pdf, audio, or video preview

kind

string

Allowed values: command edit review question custom

Request kind: command, edit, review, question, or custom

string

Case-insensitive search in title, summary, and cwd

Responses

200

application/json

Retention for resolved requests (decision history). The daemon prunes at start and hourly; 0 disables a cap. Pending requests are never pruned.

object

keep_days

Delete resolved requests older than this many days (0 = no age cap).

integer format: int32

default: 90

max_requests

Keep at most this many resolved requests (0 = no count cap).

integer format: int32

default: 2000

max_bytes

Best-effort live database/WAL/blob byte cap, excluding free database pages (0 = unlimited).

integer format: int64

files_keep_days

Remove files belonging only to resolutions older than N days (0 = request lifetime).

integer format: int32

Example

{
  "keep_days": 90,
  "max_requests": 2000,
  "max_bytes": 0,
  "files_keep_days": 0
}

400

Invalid filter or cursor