---
title: "List capsules visible to the caller"
method: GET
path: "/api/preview/capsules"
tags: ["capsule"]
---

# List capsules visible to the caller

`GET /api/preview/capsules`

## Query parameters

- `typeId` string — Filter to a single Type by id.
- `collectionId` string — Filter to a collection by id. Requires `typeId`.
- `archived` 'true' | 'false' — Set to `true` to list archived capsules instead of active ones.
- `projectId` string — Filter to a single Project by id.
- `skill` string — Set to `true` (or `1`) to return only capsules that are Skills.
- `tag` string — Filter to capsules carrying this tag.
- `category` string — Filter to capsules in this category slug.
- `created_within` '24h' | '7d' | '30d' — Relative recency window — only capsules created within it.
- `incomplete` 'true' | 'false' — Set to `true` to list only unfinished (capture-first) capsules still awaiting completion. Honoured on the active list only; the archived view is history, not a work queue.
- `cursor` string — Opaque keyset cursor from a previous page's `nextCursor`.
- `limit` integer — Page size, 1–100. Defaults to 30.
- `sort` 'newest' | 'oldest' | 'updated' | 'title_asc' | 'ref_desc' | 'ref_asc' | 'archived_newest' | 'archived_oldest' — Sort order. The valid keys depend on the list context: `newest`, `oldest`, `updated`, `title_asc` for all capsules; `ref_desc`, `ref_asc` (plus `newest`, `updated`, `title_asc`) within a Type; `archived_newest`, `archived_oldest` (plus `newest`, `title_asc`) when `archived=true`. An out-of-context key is rejected.
- `maxBytes` integer — Opt-in response size budget in bytes (size-budgeted paging).
- `contentLevel` 'metadata' | 'full' — Row content projection on the size-budgeted path. Defaults to `metadata`.
- `fields` string — Comma-separated opt-in heavy columns to include on full rows.
- `include` string — Opt-in enrichments. `cover` attaches each card's featured image (web only).
- `ws` string — Optional workspace context for the request. Same value rules as the MCP `workspace` tool argument. Omit to use the caller's default workspace.

## Response `200`

Successful response

- object
  - `capsules` object[], required
    - `content_md` string, nullable
    - `created_at` string
    - `id` string, required — UUID v4 string
    - `incomplete` boolean
    - `is_encrypted` boolean
    - `is_stale` boolean
    - `log` object
      - `append_via` string, required
      - `bound_type` object, required
        - `id` string, required — UUID v4 string
        - `name` string, required
        - `slug` string, required
      - `owned_log_ref` string, nullable, required
      - `role` 'owner' | 'log', required
    - `ref_id` integer — Numeric capsule ref id.
    - `title` string
    - `type_id` string — UUID v4 string
    - `type_name` string
    - `type_slug` string
    - `updated_at` string
  - `hasMore` boolean
  - `nextCursor` string, nullable

## Changes

> 6 revisions in range; 3 could not be searched.

- **2026-08-29** `9ca3e15b9d44` — 18 info
  - added the new optional `query` request parameter `archived`
  - added the new optional `query` request parameter `category`
  - added the new optional `query` request parameter `collectionId`
  - added the new optional `query` request parameter `contentLevel`
  - …14 more

[Change history](https://skmtc.dev/symbol/apis/symbol-api/changes/api/preview/capsules/get.md)

---

[API](https://skmtc.dev/symbol/apis/symbol-api.md) · [All operations](https://skmtc.dev/symbol/apis/symbol-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/symbol/symbol-api/revisions/9ca3e15b9d44/schema)