Skip to main content
B2B only. customer.context.fetch (POST /v1/context/customer/fetch) is available only on a B2B instance, that is one whose user_context_isolation is strict. On a B2C instance (user_context_isolation: "equals_customer") there is no customer scope, the call is not available, and it is rejected with HTTP 400. Call GET /api/v1/auth/whoami to see which mode your instance is in: it returns user_context_isolation. On a B2C instance, fetch at user scope with user.context.fetch instead.
REST One HTTPS request, unless the answer is already cached locally: in the cache the anticipation stream fills or, in Python, the 5-minute response cache. Works in any Python or Node 20+ process, including serverless functions. Retrieve context scoped to a specific customer organization. Customer-scoped memories are visible to all users within that customer. This is useful for fetching shared organizational knowledge, company policies, and team-wide context.

Parameters

string
required
The customer identifier to fetch context for. Always required, because this call is B2B-only: a B2C instance does not accept customer_id anywhere. See B2C vs B2B.
string
Optional conversation identifier. When provided, results are biased toward memories relevant to the active conversation. When supplied, it must be a valid UUID registered via record_message.
string | string[]
One or more search queries to find relevant customer memories. If omitted, returns the most recent and highest-confidence customer-scoped memories. A single fetch searches at most 5 queries; with more, the first five are searched and the response’s retrieval.warnings says so. Send the rest in another fetch.
integer
Maximum number of memory items to return. Defaults to 10. Maximum 50.
integer
How many items each search query may contribute when search_query holds more than one. Without it, a query with many strong matches can take every place and a query with a single weaker match gets none. max_results stays the ceiling on the whole response: three queries at 5 each under max_results=10 return ten, not fifteen. Ignored with a single query. Optional; when omitted, the best max_results items overall are returned. In JavaScript and TypeScript, pass it as max_results_per_query (or maxResultsPerQuery).
string[]
Filter results to specific memory types. If omitted, all types are included.
string
Retrieval mode that controls the speed-quality tradeoff: the retrieval axis (fast vs accurate) of Retrieval Modes.For real per-mode latency on your instance, see Dashboard → Usage.
string
Controls how precisely results are filtered before they’re returned.Independent of mode; combine with either fast or accurate. For real latency on your instance, see Dashboard → Usage.
string
The moment the question is being asked, for example "2023-03-11". Synap resolves a time the question names (“in March”, “two months ago”) from that moment instead of from now, which matters when you replay a past conversation. Lenient: "2023-03-11", "2023/03/11 21:26" and "2023/03/11 (Sat) 21:26" all parse, and anything unreadable silently falls back to now instead of failing the read. Python 0.5.4 and later. JavaScript and TypeScript 0.5.4 and later, as query_date (or queryDate).
string
How the memories come back. Pass "ranked": you get one list, items, with the most relevant memory first across every type. Each item carries its type (category), its place (rank, from 1) and the score it was ranked by (metadata.rank_score). Quotes from your source conversations and documents come back as their own type, "excerpts", placed by their own score. You can pass the list to your model as it is: there is nothing to merge or sort.The typed lists (facts, preferences, …) are filled either way, with one difference: the quotes from your source conversations and documents are in excerpts and not in facts, so code that reads only facts no longer sees them. The list is in rank order, but when the token budget is exceeded the cut keeps whole memory types in a fixed order, so it does not always keep the best items overall. In JavaScript and TypeScript, pass it as response_shape (or responseShape).
dict[str, str]
The level of your scope ladder to read from, below the customer, for example {"customer": "acme", "team": "payments"}. Use the same customer as customer_id. Only needed when your ladder has a level between customer and user. Every level above the one you read from must be named. A path is refused (400) if it has a gap, if it reaches the user level (use user.context.fetch for that), or if nested scoping is off or the ladder has not been accepted. Python 0.4.6 and later. JavaScript and TypeScript 0.5.10 and later, as scope_path (or scopePath).

Returns

A ContextResponse with the following fields:
array
With response_shape="ranked": every memory once, most relevant first across types. Each item has id, rank (1 is best), category (facts, preferences, episodes, emotions, temporal_events or excerpts), content, metadata.rank_score (higher is better), confidence, the date fields and matched_queries. Empty with by_type.
array
With response_shape="ranked": the quotes from your source conversations and documents, as their own list. With by_type they are filed under facts.
array
Array of fact memories relevant to the query. Every memory item also carries matched_queries: the search_query strings that found it, in the order you sent them. A result of a subquery the server wrote names the query it came from. In JavaScript and TypeScript, read it as matchedQueries.
array
Array of preference memories.
array
Array of episode memories.
array
Array of emotion memories.
object
Response metadata including total_results, query_time_ms, tokens_used, scope, and mode.

Example

Response
Customer-scoped memories take priority over client-scoped memories when they cover the same topic, following the scope chain priority rules. To merge customer and client context in a single call, use sdk.context.fetch.

Ranked results

With response_shape="ranked", read items in order. The most relevant memory comes first, whatever its type.

Raises

  • InvalidInputError: when mode is not "fast" or "accurate".
  • InvalidInputError: when precision_level is not "high" or "medium".
  • InvalidInputError: when response_shape is not "ranked" or "by_type".
  • InvalidInputError: when the server refuses scope_path (see above).
  • CustomerIdNotAcceptedError, a subclass of InvalidInputError: on a B2C instance, which has no customer scope (Python 0.5.12 and JavaScript 0.5.11 and later; in Python it is also a ValueError).
  • AuthenticationError with the message “SDK not initialized”: when called before await sdk.initialize() (Python). JavaScript resolves the client’s identity on the first call instead.
  • AuthenticationError: when the API key is invalid or revoked.

See also