---
title: "Get Context"
method: GET
path: "/v1/context"
tags: ["v1"]
---

# Get Context

`GET /v1/context`

## Request

- Base URL: `https://api.korely.ai`
- URL: `https://api.korely.ai/v1/context`
- Auth: HTTP bearer

A block for the prompt: what the store knows about the end user, and
the facts and memories most relevant to `query`, as Markdown within
`token_budget` tokens.

No text is generated: retrieval and layout, the question only embedded to
rank. `context` is
the whole block; `stable` (the same from one call to the next) and
`volatile` (this question's part) are its two halves, for a model
provider's prompt cache. `degraded` is true when part of it could not be
retrieved, `degraded_parts` says which, and the block then ends with a
note saying so to the model.

## Query parameters

- `query` string, required
- `user_id` string, nullable: End user to build context for.
- `agent_id` string, nullable: One agent's namespace: its facts and its memories only, as every other read with an agent_id.
- `token_budget` integer: Tokens the block may take, 50 to 8000. Default 800; we recommend 4000 for an agent that answers questions about the past. On 60 LongMemEval questions the memory holding the answer reached the block for 82% of them at 2000 tokens (2 Oct 2026; 0.1.28 left the block up to 2000 tokens as it was). Above 2000 tokens the block shows more memories since 0.1.28: at 4000, 15 more of 282 LoCoMo multi-hop questions were answered (12 Oct 2026). A larger budget is a larger prompt: keep it low where latency matters, as in a voice agent.
- `known_as_of` string, nullable: ISO date/datetime: the block as the store could have built it then: the facts it had learned by then, true then as it knew them, and the memories it had received by then. Rebuilt with today's ranking; a memory edited since shows today's text, one deleted since stays out.
- `exclude_sessions` boolean: Leave out the work sessions (memories written with `kind: session`, what a coding assistant's hooks save) and the facts only they state, for a block about what was said and decided. Default false: everything.

## Response `200`

Successful Response

- ContextResponse
  - `context` string, required
  - `tokens` integer, required
  - `sources` string[], required
  - `degraded` boolean
  - `degraded_parts` string[]
  - `stable` string: The head of `context` that does not depend on the question: the reader note, the same text from one call to the next. Put it in your system prompt, where the model provider's prompt cache can reuse it.
  - `volatile` string: The rest of `context`: the facts and the memories for this question and, when part of the retrieval failed, a closing NOTE. Put it in the turn.
  - `stable_hash` string: SHA-256 (hex) of `stable`. The same value means the same prefix, so a cached system prompt is still valid.

## Other responses

- `401`: `invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.
- `403`: `forbidden`: the key lacks the scope this operation needs; `message` names it.
- `422`: `invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).
- `429`: `rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's queries of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at` or a bigger plan).
- `500`: `internal_error`: the server failed on this request; `message` holds no detail of it.
- `503`: A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry.

---

[API](https://skmtc.dev/korely/apis/korely-agents-api.md) · [All operations](https://skmtc.dev/korely/apis/korely-agents-api/llms.txt) · [OpenAPI document](https://skmtc.dev/korely/apis/korely-agents-api/revisions/8a40bf09eca1?raw)