user_id (and customer_id) is strongly recommended: it scopes the in-process anticipation cache to that user so bundles prefetched for one user can never be served on another user’s lookup.
Parameters
The conversation to fetch context for. Must be a valid UUID (e.g.
str(uuid.uuid4())), the same id you used when recording the conversation’s messages.Optional list of query strings to bias retrieval. When omitted, Synap does not run a blank search: it returns the conversation state in
conversation_context. A single fetch searches at most 5 queries; with more, the first five are searched. Every returned memory item carries matched_queries: the queries that found it, in the order you sent them. In JavaScript and TypeScript, read it as matchedQueries.Maximum number of items to return per context type. The same limit applies when the anticipation cache answers the fetch.
How many items each search query may contribute when
search_query holds more than one. max_results stays the ceiling on the whole response. This rule also applies to an anticipation-cache hit. Ignored with a single query. In JavaScript and TypeScript, pass it as max_results_per_query (or maxResultsPerQuery).Context types to include. Defaults to all available types (facts, preferences, episodes, emotions, temporal events).
Retrieval mode: the retrieval axis (
fast vs accurate) of Retrieval Modes:"fast": direct query, lower latency. Best for in-the-loop prompt assembly."accurate": LLM-enhanced queries, higher quality at higher latency. Best when you can afford the extra latency.
Controls how precisely results are filtered before they’re returned:
"high": results go through an additional relevance-refinement pass before being returned. Default."medium": skips the refinement pass for faster responses. Recall isn’t impacted (the same candidate memories are searched), but outputs are less precisely filtered.
mode; combine with either fast or accurate. For real latency on your instance, see Dashboard → Usage.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. Python 0.5.4 and later. JavaScript and TypeScript 0.5.4 and later, as query_date (or queryDate).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, so code that reads them keeps working. In JavaScript and TypeScript, pass it as response_shape (or responseShape).External user id. Strongly recommended: scopes anticipation cache lookups to the right user and avoids deriving scope from a not-yet-written conversation row.
External customer id, forwarded alongside
user_id for the same scoping reason. On B2B, if you leave it out the server uses the one this conversation was recorded with. Not accepted on B2C. See B2C vs B2B.The level of your scope ladder to read at, for example
{"customer": "acme", "team": "payments", "user": "dana"}. Usually not needed: without one, the server uses the path this conversation’s messages were first recorded with, and a user already placed at a level is reached by the ids alone. Every level above the one you name must be named. A path is refused (400) if it has a gap, 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
AContextResponse containing the retrieved context.
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.With
response_shape="ranked": the quotes from your source conversations and documents, as their own list. With by_type they are filed under facts.Correlation id, source (
cache, cloud or anticipation), TTL, and retrieval timestamp.Example
Ranked results
Withresponse_shape="ranked", read items in order. The most relevant memory comes first, whatever its type.
Raises
InvalidInputError: whenmode,precision_levelorresponse_shapeis not an accepted value.InvalidInputError: whenconversation_idis empty (Python 0.5.14 and later; all JavaScript versions).InvalidConversationIdError, a subclass ofInvalidInputError: whenconversation_idis not a valid UUID.CustomerIdNotAcceptedError, a subclass ofInvalidInputError: whencustomer_idis passed on a B2C instance (Python 0.5.12 and JavaScript 0.5.11 and later).AuthenticationErrorwith the message “SDK not initialized”: when called beforeawait sdk.initialize()(Python). JavaScript resolves the client’s identity on the first call instead.AuthenticationError: when the API key is invalid or revoked. A missing key fails earlier, when the client is created (JavaScript) or initialized (Python).NetworkTimeoutError: the SDK could not reach Synap (a timeout, or a refused or dropped connection) after its retries.ConnectionErroris the same class in both SDKs. JavaScript 0.5.13 and later; earlier JavaScript raisedServiceUnavailableErrorfor a refused or dropped connection.