---
title: "Measure what reading capsules costs in characters, alone and read together; capsules you cannot read come back not available"
method: POST
path: "/api/preview/capsules/read-cost"
tags: ["capsule"]
---

# Measure what reading capsules costs in characters, alone and read together; capsules you cannot read come back not available

`POST /api/preview/capsules/read-cost`

## Request

- Base URL: `https://symbol.chat` (the document declares no server; this is the origin it was published from)
- URL: `https://symbol.chat/api/preview/capsules/read-cost`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `__Secure-next-auth.session-token`
  - OAuth 2
    - Authorization code: `https://mcp.symbol.chat/authorize`
    - Token URL: `https://mcp.symbol.chat/token`

## Request body

- object
  - `capsule_ids` string[], required: Capsules to measure, 1 to 20 ids. A repeated id is measured once.
  - `threshold` integer: Inlined capsules larger than this many characters are flagged as worth a pointer. Default 4000.

## Response `200`

Successful response

- object
  - `capsules` union[], required: One entry per distinct requested id, in request order.
    - union
      - object
        - `available` false, required
        - `id` string, required
      - object
        - `available` true, required
        - `id` string, required
        - `measured` false, required
        - `reason` 'encrypted' | 'archived', required
        - `ref` string, required
        - `references` object[], required
          - `expansion` string, required
          - `ref` string, required
          - `title` string, nullable, required
        - `title` string, nullable, required
      - object
        - `available` true, required
        - `id` string, required
        - `measured` true, required
        - `oversize` object[], required: Inlined capsules larger than the threshold, with what a pointer would save.
          - `admits` object[], required
            - `ref` string, required
            - `title` string, nullable, required
          - `chars` integer, required
          - `edit_sites` union[], required
            - union
              - …
          - `id` string, nullable, required
          - `ref` string, nullable, required
          - `saving_chars` integer, nullable, required
          - `source_ref` string, nullable, required
          - `title` string, nullable, required
          - `withholds_linked` boolean, required
        - `parts` object[], required
          - `chars` integer, required
          - `edit_sites` union[]: `inlined` only: where the source capsule writes this ref inline.
            - union
              - …
          - `files` integer: `attachments` only: how many attachments the read carries.
          - `id` string, nullable, required
          - `kind` 'own' | 'attachments' | 'fields' | 'inlined' | 'unavailable' | 'pointer' | 'capped' | 'withheld' | 'unexpanded' | 'unresolved', required
          - `pointer` object: `inlined` only: what writing this ref as a pointer would do to the read.
            - `admits` object[], required
              - …
            - `saving_chars` integer, required
            - `withholds_linked` boolean, required
          - `potential_chars` integer, nullable: For a ref the read does not deliver: what inlining it would add, null when unknown.
          - `ref` string, nullable, required
          - `source_ref` string: `inlined` only: the ref the read fetched it by, as authored.
          - `title` string, nullable, required
        - `ref` string, required
        - `repeated_text` object[], required: Text this one read returns more than once, with what the extra copies cost.
          - `chars` integer, required
          - `cost_chars` integer, required
          - `extra_copies` integer, required
          - `paths` string[], required
          - `preview` string, required
        - `title` string, nullable, required
        - `total_chars` integer, required
  - `set` object, required
    - `repeats` object[], required: Capsules the set delivers more than once, with what the repeats cost.
      - `chars` integer, required
      - `id` string, required
      - `ref` string, nullable, required
      - `repeat_cost_chars` integer, required
      - `times` integer, required
      - `title` string, nullable, required
    - `total_chars` integer, required
  - `threshold` integer, required

## Changes

- **2026-10-27** `3a2c4ebeab51`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/symbol/apis/symbol-api/changes/api/preview/capsules/read-cost/post.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.dev/symbol/apis/symbol-api/revisions/3a2c4ebeab51?raw)