Skip to main content
REST One HTTPS request per scope you ask for, run in parallel: conversation, user and customer when you pass their id, client only when scopes names it. With a conversation_id, one more reads the conversation’s history. A scope is skipped when its answer is already cached locally (the anticipation stream cache or, in Python, the response cache). Works in any Python or Node 20+ process, including serverless functions. The recommended entry point for framework integrations. fetch() queries every scope you provide an identifier for in parallel, deduplicates the merged items (first scope wins), attributes each item to its source scope, optionally folds in the conversation’s compacted history plus recent messages, and returns a ready-to-inject formatted_context string. Pass it the identifiers you have on hand for the current turn (conversation, user, customer) and use the resulting formatted_context directly in your LLM prompt.

Parameters

str
Conversation scope identifier. When provided, the conversation scope is queried and (unless disabled) the conversation’s compacted history is included. Must be a valid UUID (e.g. str(uuid.uuid4())) registered via record_message.
str
User scope identifier. Threaded into the conversation-scope sub-fetch so per-user privacy filtering applies.
str
Customer scope identifier. Required on B2B. Not accepted on B2C: passing it is rejected with HTTP 400. See B2C vs B2B. Required for B2B deployments where customer-scoped context is in use. On a B2C deployment, leave it out entirely.
list[str]
Search queries applied to all queried scopes. Defaults to None. Without a query, the conversation scope returns its state in conversation_context, and the user scope returns its profile in profile when one exists; Synap does not run a blank search. Customer and client scopes, and a user without a profile, use their normal behavior. A single fetch searches at most 5 queries per scope; 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.
int
Maximum results per scope. The merged total may be higher across scopes. Defaults to 20. The same limit applies when the anticipation cache answers a scope’s fetch.
int
How many items each search query may contribute, per scope, when search_query holds more than one. max_results stays the ceiling for each scope. The same allocation applies to an anticipation-cache hit. Ignored with a single query. Defaults to None, which returns the best max_results items per scope overall. In JavaScript and TypeScript, pass it as max_results_per_query (or maxResultsPerQuery).
list[str]
Memory types to include. Defaults to None, which means all types.
str
Retrieval mode: the retrieval axis (fast vs accurate) of Retrieval Modes. "fast" (default) or "accurate".
str
Result precision: "high" (default) or "medium". With "high", results go through an additional relevance-refinement pass before being returned. "medium" skips the refinement pass for faster responses; recall isn’t impacted (the same candidate memories are searched), but outputs are less precisely filtered. 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. Sent to every scope queried. 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": every scope is asked for its ranked list, and you get one merged 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. formatted_context is then one numbered list in that order, for example 1. [fact] ..., 2. [temporal event] ..., 3. [excerpt] ....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).
bool
Include the conversation’s compacted history plus recent messages in the result. Defaults to True. Only effective when conversation_id is also provided.
list[str]
Explicitly limit which scopes to query (e.g. ["user", "customer"]). Defaults to None, which queries every scope for which an identifier was provided.
bool
Annotate each item with its source scope in the formatted_context output. Defaults to False.
str
"in-conversation" (default) returns the usual merged item lists. "conversation-summary" instead returns a caller profile plus summaries of the last last_n_conversations conversations: the call-start read for async integrations. Requires user_id. These three summary-mode params are forwarded only to the user-scope sub-fetch (the other scopes reject summary mode). In summary mode search_query, mode and precision_level are ignored (it is an assembly, not a retrieval), and customer_id is required on B2B.
bool
Summary mode only: include the caller profile. Defaults to True.
int
Summary mode only: how many previous conversations to summarize. Defaults to 1. Range 0–20.

Returns

A UnifiedContextResponse with merged items, scope attribution, and a formatted_context string ready for LLM injection.
array
With response_shape="ranked": every memory once, most relevant first across scopes and types, merged by metadata.rank_score. 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.
UserProfileModel | None
Summary mode only: the caller profile (attributes, overview, extras, meta). None outside summary mode.
list[ConversationSummaryModel] | None
Summary mode only: previous-conversation summaries. None outside summary mode.
str
Pre-formatted context block you can drop straight into an LLM prompt. Honors include_scope_labels and include_conversation_context.
list[str]
The scopes that were actually queried for this call, in order.
dict[str, str]
Mapping from item ID to the scope that produced it after deduplication.
object | None
When include_conversation_context=True and a conversation_id was supplied, the conversation’s compacted history and recent messages. None otherwise.

Example

Conversation-summary mode (call start)

For async integrations, fire one summary-mode fetch at call connect, keyed by the caller’s identity. It resolves a caller profile plus the last call’s summary (no retrieval, pure assembly), and folds them into formatted_context as ## Caller Profile and ## Previous Conversations sections.
The call-end counterpart is conversation.ingest_transcript.

Raises

  • InvalidInputError: when precision_level is not "high" or "medium".
  • InvalidInputError: when response_shape is not "ranked" or "by_type".
  • CustomerIdNotAcceptedError, a subclass of InvalidInputError: when customer_id is passed on a B2C instance, checked before any scope is queried. Python 0.5.12 and JavaScript 0.5.11 and later.
  • AuthenticationError: when the SDK has not been initialized (Python; call await sdk.initialize() first). JavaScript resolves the client’s identity on the first call instead.
Per-scope fetch failures are logged and skipped rather than raised, except invalid input (InvalidInputError), which is raised. A partial-scope outage therefore still returns the scopes that succeeded. See Error Codes for the full SDK exception hierarchy.

See also

  • initialize: required in Python before calling fetch; optional in JavaScript.
  • as_tool: expose fetch to an LLM as a tool definition.