API Sessions

Sessions API

Queries

sessions

List sessions ordered by most recent activity.

{
  sessions(limit: 20, offset: 0) {
    id
    cwd
    model
    gitBranch
    hookCount
    durationSeconds
    firstSeenAt
    lastSeenAt
    toolUsage { name count }
    skillsUsed { name count }
    errorCount
    summary
    prompts
    editedFiles
    subagents { agentType description }
    tokenUsage {
      inputTokens
      outputTokens
      cacheReadTokens
      cacheCreationTokens
    }
  }
}

session

Fetch a single session by ID.

{
  session(id: "abc-123") {
    id
    cwd
    model
    gitBranch
    errors {
      toolName
      errorMessage
      input
      recordedAt
    }
    subagents {
      id
      agentType
      description
    }
    transcript(limit: 50, offset: 0) {
      type
      role
      content
      uuid
      timestamp
      isSidechain
    }
  }
}

Session intelligence

A compact query for answering “what happened in this session?”:

{
  session(id: "abc-123") {
    id
    status
    cwd
    model
    gitBranch
    firstSeenAt
    lastSeenAt
    durationSeconds
    prompts
    editedFiles
    skillsUsed { name count }
    toolUsage { name count }
    subagents { agentType description }
    errors { toolName errorMessage recordedAt }
    tokenUsage { inputTokens outputTokens cacheReadTokens cacheCreationTokens }
  }
}

Session.hooks

Fetch hooks within a session with the same filters as the top-level hooks query:

{
  session(id: "abc-123") {
    hooks(filter: { toolName: "Bash" }, limit: 20) {
      id
      eventType
      recordedAt
      parsedInput {
        ... on BashInput { command description }
      }
    }
  }
}

Mutations

summarizeSession

Generate a 1–2 sentence LLM summary for a session The result is cached in sessions.summary and returned immediately.

mutation {
  summarizeSession(sessionId: "abc-123") {
    id
    summary
  }
}

The server calls an LLM CLI to generate the summary. To change the command, modify generateSummaryViaVenu() in graph/helpers.go.