Ellipsis APIReferenceSessions

Search Sessions

Search the customer's sessions, 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).

GET
/v1/sessions/search

Search the customer's sessions, 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).

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Query Parameters

q*Q
scope?SessionSearchScope

What text a search query is matched against: the session log's record text, the session recaps (summaries), or both.

Default"both"

Value in

  • "records"
  • "recaps"
  • "both"
source?array<>|null
author_id?array<integer>|

Attributed GitHub user account ids.

agent_config_id?array<string>|

Saved agent config ids (ORed with author_id).

session_ids?array<string>|null
repo?|

"owner/name" (exact) or a bare repo name.

status?array<>|null
start?|null
end?|null
limit?Limit
Default20

Header Parameters

user-agent?string|null

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/sessions/search?q=string"
{  "attributed_users": {    "property1": {      "avatar_url": "string",      "id": 0,      "login": "string",      "type": "User"    },    "property2": {      "avatar_url": "string",      "id": 0,      "login": "string",      "type": "User"    }  },  "results": [    {      "matched": [        "string"      ],      "recap_snippet": "string",      "record_hit_count": 0,      "record_hits": [],      "session": {        "agent_config_id": "string",        "attributed_user": {          "avatar_url": "string",          "id": 0,          "login": "string",          "type": "User"        },        "attribution_id": "string",        "attribution_type": "github_user",        "client_version": "string",        "config_override": {},        "context_repository": "string",        "cost_fee": 0,        "cost_sandbox_cpu": 0,        "cost_sandbox_memory": 0,        "cost_tokens": 0,        "created_at": "2019-08-24T14:15:22Z",        "customer_id": "string",        "default_resolution": "repo_default",        "exit_status": "completed",        "harness": "claude_code",        "id": "string",        "last_activity_at": "2019-08-24T14:15:22Z",        "last_message_at": "2019-08-24T14:15:22Z",        "live_summary": "string",        "metadata": {},        "output_prs": [          {            "gh_pr_id": 0,            "number": 0,            "repo_full_name": "string",            "title": "string",            "url": "string"          }        ],        "parent_agent_session_id": "string",        "parent_kind": "continuation",        "prompt": "string",        "prompting": {          "blocked_reason": "mention_surface",          "detail": "string",          "enabled": true,          "surface_name": "string"        },        "replayed_from_session_id": "string",        "resolved_budget_cents": 0,        "resolved_budget_source": "system",        "sandbox_id": "string",        "session_key": "string",        "session_state": "idle",        "source": "react",        "status": "scheduled",        "status_reason": "string",        "stopped_at": "2019-08-24T14:15:22Z",        "stopped_by": 0,        "stopped_by_user": {          "avatar_url": "string",          "id": 0,          "login": "string",          "type": "User"        },        "surface": {          "run": "scheduled",          "session": "alive",          "status": "string"        },        "tokens_cache_creation": 0,        "tokens_cache_read": 0,        "tokens_input": 0,        "tokens_model": "string",        "tokens_output": 0,        "tokens_total": 0,        "updated_at": "2019-08-24T14:15:22Z",        "webhook_id": "string",        "webhook_type": "github.issue"      }    }  ]}

Start Agent Session

Start a new agent session. Provide at most one of config_id, config, or template_id; with none, the customer's default-config ladder resolves the config. 400 when idle_start is combined with prompt or handoff, or when a handoff is combined with any config source or override.

Sync Agent Session

Sync a Claude Code transcript from a developer laptop. Requires a user token (device-flow `agent login`): the user is part of the sync's idempotency key, so API keys and sandbox tokens are rejected with a 403 rather than silently attributed.