---
title: "Dry-run fact extraction (preview, no persistence)"
method: POST
path: "/v1/default/banks/{bank_id}/memories/dry-run-extract"
tags: ["Memory"]
---

# Dry-run fact extraction (preview, no persistence)

`POST /v1/default/banks/{bank_id}/memories/dry-run-extract`

## Request

- Base URL: `https://hindsight.vectorize.io` (the document declares no server; this is the origin it was published from)
- URL: `https://hindsight.vectorize.io/v1/default/banks/{bank_id}/memories/dry-run-extract`
- Auth: none declared
- TypeScript: <https://skmtc.dev/vectorize/apis/hindsight-http-api/docs/v1/default/banks/:bank_id/memories/dry-run-extract/post.ts> (a function with typed inputs; its response is checked against the schema)

Preview what the retain step would extract from text WITHOUT changing the bank — no entity resolution, links, embeddings, or persistence. Returns the candidate facts and the LLM token usage. Every prompt-affecting setting (retain mission, extraction mode, chunk size, …) is overridable in the body to A/B a candidate config against the bank's current one. This is a read-only tool: nothing is stored.

## Path parameters

- `bank_id` string, required

## Headers

- `authorization` string, nullable

## Request body

- DryRunExtractRequest: Request to run fact extraction ONLY (no resolution/links/embeddings/persistence). Every field below the content/context/date is a prompt-affecting override applied just for this call — used to preview what a candidate retain mission (or any extraction setting) would extract, without changing the bank. Unset (null) fields fall back to the bank's resolved config.
  - `content` union, required: The raw content to retain or extract from. Either a plain string or an ordered list of content blocks.
    - string
    - union[]
      - union
        - TextContentBlock: A run of text within a multimodal item, in the position the caller wrote it.
          - `type` 'text', required
          - `text` string, required
        - ImageContentBlock: An image within a multimodal item, in the position the caller wrote it.
          - `type` 'image', required
          - `source` Base64AttachmentSource, required: Inline attachment bytes, base64-encoded. The only source type in this version. ``url`` (server-side fetch) and ``blob_id`` (pre-uploaded handle) are the natural next ones, which is why this is modelled as a discriminated union on ``type`` rather than as bare fields.
            - `type` 'base64'
            - `media_type` string, required: MIME type of the attachment, e.g. 'image/png' or 'application/pdf'. Any well-formed type is accepted; whether the model can read it is the model's answer to give, and a provider that rejects it fails the retain with its own error.
            - `data` string, required: Base64-encoded bytes (no data: URI prefix).
        - FileContentBlock: A non-image attachment — a PDF, a spreadsheet — in its input position. This stays distinct from ``image`` because providers use different request parts for images and documents; retaining the caller's kind avoids guessing.
          - `type` 'file', required
          - `source` Base64AttachmentSource, required: Inline attachment bytes, base64-encoded. The only source type in this version. ``url`` (server-side fetch) and ``blob_id`` (pre-uploaded handle) are the natural next ones, which is why this is modelled as a discriminated union on ``type`` rather than as bare fields.
            - `type` 'base64'
            - `media_type` string, required: MIME type of the attachment, e.g. 'image/png' or 'application/pdf'. Any well-formed type is accepted; whether the model can read it is the model's answer to give, and a provider that rejects it fails the retain with its own error.
            - `data` string, required: Base64-encoded bytes (no data: URI prefix).
          - `filename` string, nullable: Original filename, passed to providers that show one to the model (e.g. OpenAI).
  - `context` string: Optional context about the content.
  - `timestamp` string, date-time, nullable: Reference timestamp for resolving relative times (ISO 8601).
  - `agent_name` string, nullable: Deprecated: describe the speaker in `context` instead. Narrator override (memory owner) primed in the prompt; still honored for backwards compatibility.
  - `strategy` string, nullable: Name of a retain strategy to extract under (a key of the bank's `retain_strategies`). Omit it and the bank's `retain_default_strategy` applies, exactly as it does for a retain that names none.
  - `retain_mission` string, nullable
  - `retain_extraction_mode` string, nullable
  - `retain_custom_instructions` string, nullable
  - `retain_extract_causal_links` boolean, nullable
  - `retain_chunk_size` integer, nullable
  - `entity_labels` LabelGroupInput[], nullable: Controlled vocabulary for entity labels (overrides the bank's config for this call)
    - `key` string, required
    - `description` string
    - `type` 'value' | 'multi-values' | 'text' | 'multi-text' | 'map'
    - `optional` boolean
    - `tag` boolean
    - `values` LabelValue[]
      - `value` string, required
      - `description` string
    - `fields` object
  - `entities_allow_free_form` boolean, nullable
  - `llm_output_language` string, nullable

## Response `200`

Successful Response

- DryRunExtractionResult: Result of dry-run fact extraction: candidate facts, the chunks they came from, and aggregated LLM token usage.
  - `facts` ExtractedFact[]: Candidate facts the retain step would extract.
    - `text` string, required: The extracted fact text.
    - `fact_type` string, required: Perspective classification: 'world' or 'experience'.
    - `occurred_start` string, nullable: ISO timestamp the fact's event started, if dated.
    - `occurred_end` string, nullable: ISO timestamp the fact's event ended, if dated.
    - `entities` string[]: Raw (unresolved) entity names mentioned in the fact.
    - `chunk_index` integer, nullable: Index into `chunks` of the chunk this fact came from; null if it could not be attributed.
    - `attachments` ExtractedFactAttachment[]: Attachments from user input that this fact is attributed to / associated with.
      - `block_index` integer, required: Index of the content block in user's input (0-based)
      - `type` 'image' | 'file', required: Content block type ('image' or 'file')
      - `media_type` string, required: MIME media type of the attachment, e.g. 'image/png'
  - `chunks` ExtractionChunk[]: The chunks the input was cut into before extraction. Already computed on every path; returned because `retain_chunk_size` is otherwise a number with no visible effect.
    - `text` string, required: The chunk as the extractor saw it.
    - `fact_count` integer, required: How many facts came out of this chunk.
  - `usage` TokenUsage: Token usage metrics for LLM calls. Tracks input/output tokens for a single request to enable per-request cost tracking and monitoring.
    - `input_tokens` integer: Number of input/prompt tokens consumed
    - `output_tokens` integer: Number of visible output/completion tokens generated (excludes reasoning/thoughts)
    - `total_tokens` integer: Total tokens (input + output, excludes thoughts)
    - `cached_tokens` integer: Cached/cache-read prompt tokens, when reported by the provider
    - `thoughts_tokens` integer: Reasoning/thinking tokens generated by the model. Billed at the output rate by some providers (e.g. Gemini 2.5+ family) but not surfaced in the visible response.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-04** `4fda98b75f63`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/vectorize/apis/hindsight-http-api/changes/v1/default/banks/:bank_id/memories/dry-run-extract/post.md)

---

[API](https://skmtc.dev/vectorize/apis/hindsight-http-api.md) - [All operations](https://skmtc.dev/vectorize/apis/hindsight-http-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vectorize/apis/hindsight-http-api/revisions/951fd4ce91d1?raw)