Insights API

Synthesize an answer from accumulated memories in a space - unlike Search, which returns raw matching memories, Insights runs an agentic pass over the space and returns a synthesized response to your query.

Generate Insights

POST /v1/insights
Authorization: Bearer anona_live_YOUR_KEY
Content-Type: application/json

Request Body:

{
  "space_id": "spc_a1b2c3d4",
  "query": "What have we learned about Alice's career?"
}

Parameter	Type	Required	Description
`space_id`	string	Yes	Which space to synthesize from
`query`	string	Yes	What you want to learn

Response (200 OK):

{
  "status": "complete",
  "insights": "Alice has progressed from junior to senior engineer over 6 years, specializing in distributed systems. She has taken on mentorship responsibilities recently.",
  "usage": {
    "input_tokens": 340,
    "output_tokens": 58
  }
}

Python SDK:

answer = client.insights(
    space_id="spc_a1b2c3d4",
    query="What have we learned about Alice's career?"
)
print(answer)

client.insights() returns the synthesized string directly (or None if nothing was found).

How It Works

Insights is read-only - it doesn’t write new memories. It runs a multi-step lookup (recalling facts, expanding context, searching observations) internally and returns a single synthesized answer rather than a ranked list. Quality improves as more relevant memories accumulate in the space.

Error Responses

Status	Code	Cause
400	`bad_request`	Missing `query` or `space_id`
401	`unauthorized`	Missing/invalid API key
403	`forbidden`	Space not owned by your org
404	`not_found`	Space doesn’t exist
429	`rate_limited`	Quota or rate limit exceeded

See the full error reference.

Next Steps

Search API

Query memories for specific information

Spaces API

Manage memory spaces

​Insights API

​Generate Insights

​How It Works

​Error Responses

​Next Steps