← Spaces

list-snapshots

Browse snapshot metadata with filtering and pagination. Perfect for building UIs or reviewing recent activity.

Overview

The list-snapshots tool provides paginated access to snapshot metadata without the computational overhead of semantic search. Use it when you need to browse chronologically, filter by category, or build user interfaces.

Key Differences from query-workspace

list-snapshots

  • • Chronological ordering
  • • No embedding computation
  • • Fast metadata retrieval
  • • Category filtering
  • • Pagination support

query-workspace

  • • Relevance-based ranking
  • • Semantic similarity search
  • • Natural language queries
  • • No pagination (top N results)
  • • Higher computational cost

When to Use

Use this tool when you need to:

  • • Browse recent snapshots chronologically
  • • Build a UI showing conversation history
  • • Filter snapshots by category or scope
  • • Implement pagination in applications
  • • Review activity without specific search intent
  • • Get a quick overview of workspace content

Parameters

workspaceIdOPTIONAL

Type: string

The UUID of the workspace to list snapshots from. If omitted, uses your default workspace.

Default: User's default workspace
limitOPTIONAL

Type: number

Number of snapshots to return per page.

Default: 20 Range: 1-100
offsetOPTIONAL

Type: number

Number of snapshots to skip (for pagination).

Default: 0 Example: offset=20 returns results 21-40
categoryOPTIONAL

Type: string

Filter snapshots by AI-generated category.

Options: - planning - implementation - research - debugging - documentation - decision - question - general
scopeOPTIONAL

Type: string

Filter snapshots by privacy scope.

Options: - private   (only you can see) - workspace (team can see) - global    (public) Default: returns all scopes you have access to
orderByOPTIONAL

Type: string

Sort order for results.

Options: - created_desc  (newest first - default) - created_asc   (oldest first) - updated_desc  (recently modified first) - updated_asc   (least recently modified first)

Response

Returns a paginated list of snapshot metadata:

{
  "success": true,
  "snapshots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "summary": "Discussed OAuth 2.0 implementation with Supabase Auth",
      "category": "implementation",
      "scope": "workspace",
      "keyPoints": [
        "OAuth 2.0 chosen for authentication",
        "Supabase Auth provides simplicity"
      ],
      "concepts": ["authentication", "oauth", "supabase"],
      "actionItems": ["Set up GitHub provider", "Configure Google OAuth"],
      "createdAt": "2025-10-15T14:30:00Z",
      "updatedAt": "2025-10-15T14:30:00Z",
      "metadata": {
        "client": { "name": "Claude Desktop" },
        "conversation": { "messageCount": 23 }
      }
    }
  ],
  "pagination": {
    "total": 156,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Pagination Object

total

Total number of snapshots matching the filters

limit

Number of results in this response

offset

Starting position of these results

hasMore

Whether there are additional pages available

Examples

Basic Usage

list-snapshots({})

Returns the 20 most recent snapshots from your default workspace

With Pagination

list-snapshots({
  limit: 50,
  offset: 100
})

Get snapshots 101-150

Filter by Category

list-snapshots({
  category: "implementation",
  limit: 30
})

Get 30 most recent implementation-related snapshots

Private Snapshots Only

list-snapshots({
  scope: "private",
  orderBy: "updated_desc"
})

Get your private snapshots, sorted by most recently updated

Specific Workspace

list-snapshots({
  workspaceId: "workspace-uuid-here",
  category: "decision",
  limit: 10
})

Get 10 most recent decision snapshots from a specific workspace

Best Practices

  • ✓Use appropriate page sizes: Larger pages reduce requests but increase response size
  • ✓Combine filters: Category + scope filters help narrow results efficiently
  • ✓Check hasMore: Use the pagination.hasMore field to determine if there are additional pages
  • ✓Consider sorting: Use updated_desc to see what's been modified recently
  • ✓Use query-workspace for search: Don't paginate through all snapshots to find something - use semantic search instead

Related

query-workspace →

Search snapshots using semantic similarity

get-snapshot →

Retrieve full snapshot content by ID

Scopes & Privacy →

Understanding the three-tier privacy system

AI Enrichment →

How categories and key points are generated