GET /sessions/search
Search sessions over steps, recaps, and pull requests.
Grouped by session, over everything a session left behind: step text, recap text, created PRs, and recap-embedding similarity. This is how an agent answers "did Tony look into X?": resolve the author via /github/members, search, then read the winning session via /sessions/{id} (recap) and /sessions/{id}/records (transcript).
curl "https://api.ellipsis.dev/v1/sessions/search?q=..." \
-H "Authorization: Bearer $ELLIPSIS_API_KEY"{
"attributed_users": {},
"results": [
{
"matched": [
"string"
],
"recap_snippet": "string",
"record_hit_count": 0,
"record_hits": [],
"session": {
"agent": {
"config": {
"budget": {},
"claude": {},
"codex": {},
"ellipsis": {},
"environment": {},
"input": {},
"mcp_servers": [],
"output": {},
"permissions": {},
"skills": [],
"trigger": "string"
},
"config_id": "string",
"override": {},
"source": "explicit"
},
"attribution": {
"id": "string",
"type": "github_user",
"user": {
"avatar_url": "string",
"id": 0,
"login": "string",
"type": "User"
}
},
"budget": {
"cents": 0,
"source": "system"
},
"context_repository": "string",
"cost": {
"fee": 0,
"llm": 0,
"sandbox_cpu": 0,
"sandbox_memory": 0,
"total": 0
},
"created_at": "2026-01-01T00:00:00Z",
"exit_status": "completed",
"git": {
"repos": []
},
"harness": "claude_code",
"id": "string",
"last_activity_at": "2026-01-01T00:00:00Z",
"last_message_at": "2026-01-01T00:00:00Z",
"metadata": {},
"parent": {
"kind": "continuation",
"replayed_from_session_id": "string",
"session_id": "string"
},
"prompt": "string",
"prompting": {
"blocked_reason": "mention_surface",
"detail": "string",
"enabled": false,
"surface_name": "string"
},
"session_state": "idle",
"source": "react",
"status": "scheduled",
"status_reason": "string",
"stopped": {
"at": "2026-01-01T00:00:00Z",
"by": 0,
"by_user": {
"avatar_url": "string",
"id": 0,
"login": "string",
"type": "User"
}
},
"summary": {
"created_at": "2026-01-01T00:00:00Z",
"description": "string"
},
"surface": {
"run": "scheduled",
"session": "alive",
"status": "string"
},
"tokens": {
"cache_creation": 0,
"cache_read": 0,
"input": 0,
"model": "",
"output": 0,
"total": 0
},
"updated_at": "2026-01-01T00:00:00Z"
}
}
]
}import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.sessions.search()
print(result){
"attributed_users": {},
"results": [
{
"matched": [
"string"
],
"recap_snippet": "string",
"record_hit_count": 0,
"record_hits": [],
"session": {
"agent": {
"config": {
"budget": {},
"claude": {},
"codex": {},
"ellipsis": {},
"environment": {},
"input": {},
"mcp_servers": [],
"output": {},
"permissions": {},
"skills": [],
"trigger": "string"
},
"config_id": "string",
"override": {},
"source": "explicit"
},
"attribution": {
"id": "string",
"type": "github_user",
"user": {
"avatar_url": "string",
"id": 0,
"login": "string",
"type": "User"
}
},
"budget": {
"cents": 0,
"source": "system"
},
"context_repository": "string",
"cost": {
"fee": 0,
"llm": 0,
"sandbox_cpu": 0,
"sandbox_memory": 0,
"total": 0
},
"created_at": "2026-01-01T00:00:00Z",
"exit_status": "completed",
"git": {
"repos": []
},
"harness": "claude_code",
"id": "string",
"last_activity_at": "2026-01-01T00:00:00Z",
"last_message_at": "2026-01-01T00:00:00Z",
"metadata": {},
"parent": {
"kind": "continuation",
"replayed_from_session_id": "string",
"session_id": "string"
},
"prompt": "string",
"prompting": {
"blocked_reason": "mention_surface",
"detail": "string",
"enabled": false,
"surface_name": "string"
},
"session_state": "idle",
"source": "react",
"status": "scheduled",
"status_reason": "string",
"stopped": {
"at": "2026-01-01T00:00:00Z",
"by": 0,
"by_user": {
"avatar_url": "string",
"id": 0,
"login": "string",
"type": "User"
}
},
"summary": {
"created_at": "2026-01-01T00:00:00Z",
"description": "string"
},
"surface": {
"run": "scheduled",
"session": "alive",
"status": "string"
},
"tokens": {
"cache_creation": 0,
"cache_read": 0,
"input": 0,
"model": "",
"output": 0,
"total": 0
},
"updated_at": "2026-01-01T00:00:00Z"
}
}
]
}import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.sessions.search();
console.log(result);{
"attributed_users": {},
"results": [
{
"matched": [
"string"
],
"recap_snippet": "string",
"record_hit_count": 0,
"record_hits": [],
"session": {
"agent": {
"config": {
"budget": {},
"claude": {},
"codex": {},
"ellipsis": {},
"environment": {},
"input": {},
"mcp_servers": [],
"output": {},
"permissions": {},
"skills": [],
"trigger": "string"
},
"config_id": "string",
"override": {},
"source": "explicit"
},
"attribution": {
"id": "string",
"type": "github_user",
"user": {
"avatar_url": "string",
"id": 0,
"login": "string",
"type": "User"
}
},
"budget": {
"cents": 0,
"source": "system"
},
"context_repository": "string",
"cost": {
"fee": 0,
"llm": 0,
"sandbox_cpu": 0,
"sandbox_memory": 0,
"total": 0
},
"created_at": "2026-01-01T00:00:00Z",
"exit_status": "completed",
"git": {
"repos": []
},
"harness": "claude_code",
"id": "string",
"last_activity_at": "2026-01-01T00:00:00Z",
"last_message_at": "2026-01-01T00:00:00Z",
"metadata": {},
"parent": {
"kind": "continuation",
"replayed_from_session_id": "string",
"session_id": "string"
},
"prompt": "string",
"prompting": {
"blocked_reason": "mention_surface",
"detail": "string",
"enabled": false,
"surface_name": "string"
},
"session_state": "idle",
"source": "react",
"status": "scheduled",
"status_reason": "string",
"stopped": {
"at": "2026-01-01T00:00:00Z",
"by": 0,
"by_user": {
"avatar_url": "string",
"id": 0,
"login": "string",
"type": "User"
}
},
"summary": {
"created_at": "2026-01-01T00:00:00Z",
"description": "string"
},
"surface": {
"run": "scheduled",
"session": "alive",
"status": "string"
},
"tokens": {
"cache_creation": 0,
"cache_read": 0,
"input": 0,
"model": "",
"output": 0,
"total": 0
},
"updated_at": "2026-01-01T00:00:00Z"
}
}
]
}No request body.
{
"properties": {
"attributed_users": {
"additionalProperties": {
"$ref": "#/components/schemas/GithubAccountSnippet"
},
"type": "object"
},
"results": {
"items": {
"properties": {
"matched": {
"items": {
"type": "string"
},
"type": "array"
},
"recap_snippet": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"record_hit_count": {
"default": 0,
"type": "integer"
},
"record_hits": {
"default": [],
"items": {
"properties": {
"attribution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"attribution_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"config_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"format": "date-time",
"type": "string"
},
"execution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"git": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
]
},
"id": {
"type": "string"
},
"record_type": {
"type": "string"
},
"session_id": {
"type": "string"
},
"session_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"session_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string"
},
"stream_seq": {
"type": "integer"
}
},
"required": [
"id",
"session_id",
"stream_seq",
"record_type",
"created_at",
"snippet"
],
"type": "object"
},
"type": "array"
},
"session": {
"properties": {
"agent": {
"properties": {
"config": {
"additionalProperties": false,
"properties": {
"budget": {
"type": "object"
},
"claude": {
"type": "object"
},
"codex": {
"type": "object"
},
"ellipsis": {
"type": "object"
},
"environment": {
"type": "object"
},
"input": {
"type": "object"
},
"mcp_servers": {
"type": "array"
},
"output": {
"type": "object"
},
"permissions": {
"type": "object"
},
"skills": {
"type": "array"
},
"trigger": {
"type": "object"
}
},
"type": "object"
},
"config_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"override": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
]
},
"source": {
"enum": [
"explicit",
"inline",
"template",
"repo_default",
"account_default",
"platform_default",
"trigger",
"builtin"
],
"type": "string"
}
},
"required": [
"config",
"source"
],
"type": "object"
},
"attribution": {
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"user": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
"budget": {
"properties": {
"cents": {
"default": 0,
"type": "integer"
},
"source": {
"enum": [
"system",
"account",
"config",
"run"
],
"type": "string"
}
},
"type": "object"
},
"context_repository": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cost": {
"properties": {
"fee": {
"default": 0,
"type": "integer"
},
"llm": {
"default": 0,
"type": "integer"
},
"sandbox_cpu": {
"default": 0,
"type": "integer"
},
"sandbox_memory": {
"default": 0,
"type": "integer"
},
"total": {
"default": 0,
"type": "integer"
}
},
"type": "object"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"exit_status": {
"anyOf": [
{
"enum": [
"completed",
"budget_hit",
"payment_required",
"tool_call_failed",
"lifecycle_hook_failed",
"missing_repo_access",
"missing_token_permissions",
"missing_sandbox_variables",
"blocked",
"contact_email_required",
"cancelled",
"interrupted",
"error",
"stopped"
],
"type": "string"
},
{
"type": "null"
}
]
},
"git": {
"anyOf": [
{
"properties": {
"repos": {
"type": "array"
}
},
"type": "object"
},
{
"type": "null"
}
]
},
"harness": {
"enum": [
"claude_code",
"codex"
],
"type": "string"
},
"id": {
"type": "string"
},
"last_activity_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
]
},
"last_message_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
]
},
"metadata": {
"additionalProperties": {
"type": "string"
},
"default": {},
"type": "object"
},
"parent": {
"properties": {
"kind": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"replayed_from_session_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"session_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"prompting": {
"properties": {
"blocked_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"detail": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"surface_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"enabled"
],
"type": "object"
},
"session_state": {
"anyOf": [
{
"enum": [
"idle",
"running",
"closed"
],
"type": "string"
},
{
"type": "null"
}
]
},
"source": {
"enum": [
"react",
"manual",
"api",
"cli",
"mention",
"cron"
],
"type": "string"
},
"status": {
"enum": [
"scheduled",
"creating_sandbox",
"running",
"retrying",
"completed",
"error",
"cancelled",
"stopped"
],
"type": "string"
},
"status_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"stopped": {
"properties": {
"at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"by": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"by_user": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
"summary": {
"anyOf": [
{
"properties": {
"created_at": {
"type": "object"
},
"description": {
"type": "string"
}
},
"required": [
"description"
],
"type": "object"
},
{
"type": "null"
}
]
},
"surface": {
"anyOf": [
{
"properties": {
"run": {
"type": "object"
},
"session": {
"type": "object"
},
"status": {
"type": "object"
}
},
"required": [
"session",
"run",
"status"
],
"type": "object"
},
{
"type": "null"
}
]
},
"tokens": {
"properties": {
"cache_creation": {
"default": 0,
"type": "integer"
},
"cache_read": {
"default": 0,
"type": "integer"
},
"input": {
"default": 0,
"type": "integer"
},
"model": {
"default": "",
"type": "string"
},
"output": {
"default": 0,
"type": "integer"
},
"total": {
"default": 0,
"type": "integer"
}
},
"type": "object"
},
"updated_at": {
"format": "date-time",
"type": "string"
}
},
"required": [
"id",
"created_at",
"updated_at",
"harness",
"source",
"status",
"prompting",
"agent"
],
"type": "object"
}
},
"required": [
"session",
"matched"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"results",
"attributed_users"
],
"type": "object"
}Request
qstringrequired
scopeenum
What text a search query is matched against: the session log's record text, the session recaps (summaries), or both.
one of
recordsrecapsbothsourcearray<SessionSource>
author_idarray<integer>
Attributed GitHub user account ids.
config_idarray<string>
Saved agent config ids (ORed with author_id).
session_idsarray<string>
repostring
"owner/name" (exact) or a bare repo name.
statusarray<SessionStatus>
startstring · date-time
endstring · date-time
limitdefault
20integer