---
title: "GET /api/v1/{context_id}/state"
method: GET
path: "/api/v1/{context_id}/state"
---

# GET /api/v1/{context_id}/state

`GET /api/v1/{context_id}/state`

Get the structured memory state grouped by category. This is a composite read over six tables, each bounded by `limit` (default 100, max 500); `truncated` reports which tables had more rows. It is a snapshot, not an export: to enumerate a table completely, walk `/entities`, `/attributes`, `/relations`, or `/actions` instead.

## Path parameters

- `context_id` string, required

## Query parameters

- `limit` integer

## Response `200`

- StateResponseJson
  - `context` CategoryStateJson, required
    - `actions` ActionDetailJson[], required
      - `actor` string, required — Navigable ref of the acting entity, `entity:<type>/<name>`.
      - `confidence` number, double, required
      - `createdAt` string, required
      - `id` string, required
      - `memoryCategory` 'identity' | 'knowledge' | 'context', required — Memory category classification applied during extraction.
      - `object` string, nullable — Navigable ref (`entity:<type>/<name>`) of the acted-on entity, when the object resolved to a graph entity.
      - `objectText` string, nullable — The acted-on thing's verbatim name, when it did not resolve to an entity. At most one of `object` / `objectText` is set.
      - `occurredAt` string, nullable — Event time, distinct from assertion validity and learn time. Absent when the source stated no resolvable time.
      - `source` SourceRefJson — Compact provenance ref carried on attribute/relation detail JSON.
        - `kind` string, required — Source kind: `turn`, `document`, `upsert`, `reflect`, `elaboration`, or `consolidation`.
        - `ref` string, nullable — Compact navigable ref — `turn:<id>`, `doc:<id>`, or `trace:<id>` — when the source carries one. Document refs carry no passage index (only the passage record id is stored).
        - `sessionId` string, nullable — The session the source turn belongs to (`turn` kind only).
      - `summary` string, required
      - `validFrom` string, nullable
      - `validUntil` string, nullable
      - `verb` string, required
    - `attributes` AttributeDetailJson[], required
      - `createdAt` string, required
      - `entity` string, required — Navigable ref of the owning entity, `entity:<type>/<name>` — resolvable via `GET /entities/{type}/{name}` or the `inspect` ref grammar.
      - `id` string, required
      - `importance` number, double, required
      - `key` string, required
      - `memoryCategory` 'identity' | 'knowledge' | 'context', required — Memory category classification applied during extraction.
      - `source` SourceRefJson — Compact provenance ref carried on attribute/relation detail JSON.
        - `kind` string, required — Source kind: `turn`, `document`, `upsert`, `reflect`, `elaboration`, or `consolidation`.
        - `ref` string, nullable — Compact navigable ref — `turn:<id>`, `doc:<id>`, or `trace:<id>` — when the source carries one. Document refs carry no passage index (only the passage record id is stored).
        - `sessionId` string, nullable — The session the source turn belongs to (`turn` kind only).
      - `supersededBy` string, nullable
      - `supersedes` string, nullable
      - `validFrom` string, nullable
      - `validUntil` string, nullable
      - `value` string, required
    - `entities` EntityDetailJson[], required
      - `createdAt` string, required
      - `entityType` string, required
      - `id` string, required
      - `importance` number, double, required
      - `memoryCategory` 'identity' | 'knowledge' | 'context', required — Memory category classification applied during extraction.
      - `name` string, required
      - `updatedAt` string, required
    - `relations` RelationDetailJson[], required
      - `createdAt` string, required
      - `id` string, required
      - `label` string, required
      - `memoryCategory` 'identity' | 'knowledge' | 'context', required — Memory category classification applied during extraction.
      - `object` string, required — Navigable ref of the object entity, `entity:<type>/<name>`.
      - `source` SourceRefJson — Compact provenance ref carried on attribute/relation detail JSON.
        - `kind` string, required — Source kind: `turn`, `document`, `upsert`, `reflect`, `elaboration`, or `consolidation`.
        - `ref` string, nullable — Compact navigable ref — `turn:<id>`, `doc:<id>`, or `trace:<id>` — when the source carries one. Document refs carry no passage index (only the passage record id is stored).
        - `sessionId` string, nullable — The session the source turn belongs to (`turn` kind only).
      - `subject` string, required — Navigable ref of the subject entity, `entity:<type>/<name>` — resolvable via `GET /entities/{type}/{name}` or the `inspect` ref grammar.
      - `validFrom` string, nullable
      - `validUntil` string, nullable
  - `identity` CategoryStateJson, required
    - `actions` ActionDetailJson[], required
      - `actor` string, required — Navigable ref of the acting entity, `entity:<type>/<name>`.
      - `confidence` number, double, required
      - `createdAt` string, required
      - `id` string, required
      - `memoryCategory` 'identity' | 'knowledge' | 'context', required — Memory category classification applied during extraction.
      - `object` string, nullable — Navigable ref (`entity:<type>/<name>`) of the acted-on entity, when the object resolved to a graph entity.
      - `objectText` string, nullable — The acted-on thing's verbatim name, when it did not resolve to an entity. At most one of `object` / `objectText` is set.
      - `occurredAt` string, nullable — Event time, distinct from assertion validity and learn time. Absent when the source stated no resolvable time.
      - `source` SourceRefJson — Compact provenance ref carried on attribute/relation detail JSON.
        - `kind` string, required — Source kind: `turn`, `document`, `upsert`, `reflect`, `elaboration`, or `consolidation`.
        - `ref` string, nullable — Compact navigable ref — `turn:<id>`, `doc:<id>`, or `trace:<id>` — when the source carries one. Document refs carry no passage index (only the passage record id is stored).
        - `sessionId` string, nullable — The session the source turn belongs to (`turn` kind only).
      - `summary` string, required
      - `validFrom` string, nullable
      - `validUntil` string, nullable
      - `verb` string, required
    - `attributes` AttributeDetailJson[], required
      - `createdAt` string, required
      - `entity` string, required — Navigable ref of the owning entity, `entity:<type>/<name>` — resolvable via `GET /entities/{type}/{name}` or the `inspect` ref grammar.
      - `id` string, required
      - `importance` number, double, required
      - `key` string, required
      - `memoryCategory` 'identity' | 'knowledge' | 'context', required — Memory category classification applied during extraction.
      - `source` SourceRefJson — Compact provenance ref carried on attribute/relation detail JSON.
        - `kind` string, required — Source kind: `turn`, `document`, `upsert`, `reflect`, `elaboration`, or `consolidation`.
        - `ref` string, nullable — Compact navigable ref — `turn:<id>`, `doc:<id>`, or `trace:<id>` — when the source carries one. Document refs carry no passage index (only the passage record id is stored).
        - `sessionId` string, nullable — The session the source turn belongs to (`turn` kind only).
      - `supersededBy` string, nullable
      - `supersedes` string, nullable
      - `validFrom` string, nullable
      - `validUntil` string, nullable
      - `value` string, required
    - `entities` EntityDetailJson[], required
      - `createdAt` string, required
      - `entityType` string, required
      - `id` string, required
      - `importance` number, double, required
      - `memoryCategory` 'identity' | 'knowledge' | 'context', required — Memory category classification applied during extraction.
      - `name` string, required
      - `updatedAt` string, required
    - `relations` RelationDetailJson[], required
      - `createdAt` string, required
      - `id` string, required
      - `label` string, required
      - `memoryCategory` 'identity' | 'knowledge' | 'context', required — Memory category classification applied during extraction.
      - `object` string, required — Navigable ref of the object entity, `entity:<type>/<name>`.
      - `source` SourceRefJson — Compact provenance ref carried on attribute/relation detail JSON.
        - `kind` string, required — Source kind: `turn`, `document`, `upsert`, `reflect`, `elaboration`, or `consolidation`.
        - `ref` string, nullable — Compact navigable ref — `turn:<id>`, `doc:<id>`, or `trace:<id>` — when the source carries one. Document refs carry no passage index (only the passage record id is stored).
        - `sessionId` string, nullable — The session the source turn belongs to (`turn` kind only).
      - `subject` string, required — Navigable ref of the subject entity, `entity:<type>/<name>` — resolvable via `GET /entities/{type}/{name}` or the `inspect` ref grammar.
      - `validFrom` string, nullable
      - `validUntil` string, nullable
  - `instructions` InstructionSummaryJson[], required
    - `description` string, required
    - `id` string, required
    - `label` string, required
  - `knowledge` CategoryStateJson, required
    - `actions` ActionDetailJson[], required
      - `actor` string, required — Navigable ref of the acting entity, `entity:<type>/<name>`.
      - `confidence` number, double, required
      - `createdAt` string, required
      - `id` string, required
      - `memoryCategory` 'identity' | 'knowledge' | 'context', required — Memory category classification applied during extraction.
      - `object` string, nullable — Navigable ref (`entity:<type>/<name>`) of the acted-on entity, when the object resolved to a graph entity.
      - `objectText` string, nullable — The acted-on thing's verbatim name, when it did not resolve to an entity. At most one of `object` / `objectText` is set.
      - `occurredAt` string, nullable — Event time, distinct from assertion validity and learn time. Absent when the source stated no resolvable time.
      - `source` SourceRefJson — Compact provenance ref carried on attribute/relation detail JSON.
        - `kind` string, required — Source kind: `turn`, `document`, `upsert`, `reflect`, `elaboration`, or `consolidation`.
        - `ref` string, nullable — Compact navigable ref — `turn:<id>`, `doc:<id>`, or `trace:<id>` — when the source carries one. Document refs carry no passage index (only the passage record id is stored).
        - `sessionId` string, nullable — The session the source turn belongs to (`turn` kind only).
      - `summary` string, required
      - `validFrom` string, nullable
      - `validUntil` string, nullable
      - `verb` string, required
    - `attributes` AttributeDetailJson[], required
      - `createdAt` string, required
      - `entity` string, required — Navigable ref of the owning entity, `entity:<type>/<name>` — resolvable via `GET /entities/{type}/{name}` or the `inspect` ref grammar.
      - `id` string, required
      - `importance` number, double, required
      - `key` string, required
      - `memoryCategory` 'identity' | 'knowledge' | 'context', required — Memory category classification applied during extraction.
      - `source` SourceRefJson — Compact provenance ref carried on attribute/relation detail JSON.
        - `kind` string, required — Source kind: `turn`, `document`, `upsert`, `reflect`, `elaboration`, or `consolidation`.
        - `ref` string, nullable — Compact navigable ref — `turn:<id>`, `doc:<id>`, or `trace:<id>` — when the source carries one. Document refs carry no passage index (only the passage record id is stored).
        - `sessionId` string, nullable — The session the source turn belongs to (`turn` kind only).
      - `supersededBy` string, nullable
      - `supersedes` string, nullable
      - `validFrom` string, nullable
      - `validUntil` string, nullable
      - `value` string, required
    - `entities` EntityDetailJson[], required
      - `createdAt` string, required
      - `entityType` string, required
      - `id` string, required
      - `importance` number, double, required
      - `memoryCategory` 'identity' | 'knowledge' | 'context', required — Memory category classification applied during extraction.
      - `name` string, required
      - `updatedAt` string, required
    - `relations` RelationDetailJson[], required
      - `createdAt` string, required
      - `id` string, required
      - `label` string, required
      - `memoryCategory` 'identity' | 'knowledge' | 'context', required — Memory category classification applied during extraction.
      - `object` string, required — Navigable ref of the object entity, `entity:<type>/<name>`.
      - `source` SourceRefJson — Compact provenance ref carried on attribute/relation detail JSON.
        - `kind` string, required — Source kind: `turn`, `document`, `upsert`, `reflect`, `elaboration`, or `consolidation`.
        - `ref` string, nullable — Compact navigable ref — `turn:<id>`, `doc:<id>`, or `trace:<id>` — when the source carries one. Document refs carry no passage index (only the passage record id is stored).
        - `sessionId` string, nullable — The session the source turn belongs to (`turn` kind only).
      - `subject` string, required — Navigable ref of the subject entity, `entity:<type>/<name>` — resolvable via `GET /entities/{type}/{name}` or the `inspect` ref grammar.
      - `validFrom` string, nullable
      - `validUntil` string, nullable
  - `truncated` StateTruncationJson, required — Which of the state read's underlying tables were bounded short.
    - `actions` boolean, required
    - `attributes` boolean, required
    - `entities` boolean, required
    - `instructions` boolean, required
    - `relations` boolean, required
    - `unknowns` boolean, required
  - `unknowns` UncertaintySummaryJson[], required
    - `about` string, required
    - `reason` string, required

## Other responses

- `401` — Unauthorized
- `422` — Invalid context id
- `503` — Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.

## Changes

- **2026-08-24** `9f1598713067` — 6 info
  - added the new optional `query` request parameter `limit`
  - added the non-success response with the status `503`
  - added the required property `context/actions` to the response with the `200` status
  - added the required property `identity/actions` to the response with the `200` status
  - …2 more
- **2026-06-16** `52b41ab517b6` — 6 info
  - added the optional property `context/attributes/items/source` to the response with the `200` status
  - added the optional property `context/relations/items/source` to the response with the `200` status
  - added the optional property `identity/attributes/items/source` to the response with the `200` status
  - added the optional property `identity/relations/items/source` to the response with the `200` status
  - …2 more
- **2026-06-08** `741d58b9ef89` — 6 warning
  - removed the optional property `context/attributes/items/source` from the response with the `200` status
  - removed the optional property `context/relations/items/source` from the response with the `200` status
  - removed the optional property `identity/attributes/items/source` from the response with the `200` status
  - removed the optional property `identity/relations/items/source` from the response with the `200` status
  - …2 more

[Change history](https://skmtc.dev/surrealdb/apis/spectron/changes/api/v1/:context_id/state/get.md)

---

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