Skip to content
supermemory-new
Get started
API Reference
Client

Get user profile

profile(ClientProfileParams**kwargs) -> ProfileResponse
POST/v4/profile

Get user profile with optional search results

ParametersExpand Collapse
container_tag: str

Tag to filter the profile by. This can be an ID for your user, a project ID, or any other identifier you wish to use to filter memories.

buckets: Optional[Sequence[str]]

Specific bucket keys to return. Omit to return all configured buckets. Only relevant when “buckets” is included.

filters: Optional[Filters]

Optional metadata filters to apply to profile results and search results. Supports complex AND/OR queries with multiple conditions.

One of the following:
class FiltersOr: …
or_: Iterable[FiltersOrOr]

Array of OR filter expressions

One of the following:
class FiltersOrOrFilterCondition: …

A single filter condition based on metadata, numeric values, array contents, or string matching

key: str
value: str
filter_type: Optional[Literal["metadata", "numeric", "array_contains", "string_contains"]]
One of the following:
"metadata"
"numeric"
"array_contains"
"string_contains"
ignore_case: Optional[Union[bool, Literal["true", "false"]]]
One of the following:
bool
Literal["true", "false"]
One of the following:
"true"
"false"
negate: Optional[Union[bool, Literal["true", "false"]]]
One of the following:
bool
Literal["true", "false"]
One of the following:
"true"
"false"
numeric_operator: Optional[Literal[">", "<", ">=", 2 more]]
One of the following:
">"
"<"
">="
"<="
"="
class FiltersOrOrOr: …
or_: Iterable[object]

OR: Array of conditions or nested expressions

class FiltersOrOrAnd: …
and_: Iterable[object]

AND: Array of conditions or nested expressions

class FiltersAnd: …
and_: Iterable[FiltersAndAnd]

Array of AND filter expressions

One of the following:
class FiltersAndAndFilterCondition: …

A single filter condition based on metadata, numeric values, array contents, or string matching

key: str
value: str
filter_type: Optional[Literal["metadata", "numeric", "array_contains", "string_contains"]]
One of the following:
"metadata"
"numeric"
"array_contains"
"string_contains"
ignore_case: Optional[Union[bool, Literal["true", "false"]]]
One of the following:
bool
Literal["true", "false"]
One of the following:
"true"
"false"
negate: Optional[Union[bool, Literal["true", "false"]]]
One of the following:
bool
Literal["true", "false"]
One of the following:
"true"
"false"
numeric_operator: Optional[Literal[">", "<", ">=", 2 more]]
One of the following:
">"
"<"
">="
"<="
"="
class FiltersAndAndOr: …
or_: Iterable[object]

OR: Array of conditions or nested expressions

class FiltersAndAndAnd: …
and_: Iterable[object]

AND: Array of conditions or nested expressions

include: Optional[List[Literal["static", "dynamic", "buckets"]]]

Profile sections to return. Omit to return all sections. Pass a subset to reduce payload — e.g. [“buckets”] skips static and dynamic entirely.

One of the following:
"static"
"dynamic"
"buckets"
q: Optional[str]

Optional search query to include search results in the response

threshold: Optional[float]

Threshold for search results. Only results with a score above this threshold will be included.

minimum0
maximum1
ReturnsExpand Collapse
class ProfileResponse: …
profile: Profile
buckets: Optional[Dict[str, List[str]]]

Per-bucket memory lists, keyed by bucket key

dynamic: Optional[List[str]]

Dynamic profile information (recent memories)

static: Optional[List[str]]

Static profile information that remains relevant long-term

search_results: Optional[SearchResults]

Search results if a search query was provided

results: List[SearchResultsResult]

Search results for the provided query

id: str

Memory entry ID or chunk ID

metadata: Optional[Dict[str, object]]

Memory metadata

similarity: float

Similarity score between the query and memory entry

maximum1
minimum0
updated_at: str

Memory last update date

formatdatetime
chunk: Optional[str]

The chunk content (only present for chunk results from hybrid search)

chunks: Optional[List[SearchResultsResultChunk]]

Relevant chunks from associated documents (only included when chunks=true)

content: str

Content of the chunk

document_id: str

ID of the document this chunk belongs to

position: float

Position of chunk in the document (0-indexed)

context: Optional[SearchResultsResultContext]

Object containing version history (parents/children via updates) and related memories (extends/derives)

children: Optional[List[SearchResultsResultContextChild]]
memory: str

The contextual memory content

relation: Literal["updates", "extends", "derives"]

Relation type between this memory and its parent/child

One of the following:
"updates"
"extends"
"derives"
updated_at: str

Contextual memory last update date

formatdatetime
metadata: Optional[Dict[str, object]]

Contextual memory metadata

version: Optional[float]

Relative version distance from the primary memory (+1 for direct child, +2 for grand-child, etc.)

parents: Optional[List[SearchResultsResultContextParent]]
memory: str

The contextual memory content

relation: Literal["updates", "extends", "derives"]

Relation type between this memory and its parent/child

One of the following:
"updates"
"extends"
"derives"
updated_at: str

Contextual memory last update date

formatdatetime
metadata: Optional[Dict[str, object]]

Contextual memory metadata

version: Optional[float]

Relative version distance from the primary memory (-1 for direct parent, -2 for grand-parent, etc.)

One of the following:
documents: Optional[List[SearchResultsResultDocument]]

Associated documents for this memory entry

id: str

Document ID

created_at: str

Document creation date

formatdatetime
updated_at: str

Document last update date

formatdatetime
metadata: Optional[Dict[str, object]]

Document metadata (only included when documents=true)

summary: Optional[str]

Document summary (only included when summaries=true)

title: Optional[str]

Document title (only included when documents=true)

type: Optional[str]

Document type (only included when documents=true)

filepath: Optional[str]

Filepath of the source document this memory or chunk came from

is_aggregated: Optional[bool]

Indicates if this memory was created by aggregating multiple source memories

memory: Optional[str]

The memory content (only present for memory results)

root_memory_id: Optional[str]

ID of the root (first version) memory entry this one descends from. Null for memories that have never been superseded. Only present on memory results, not on standalone chunk results.

version: Optional[float]

Version number of this memory entry

timing: float

Search timing in milliseconds

total: float

Total number of search results

Get user profile

import os
from supermemory import Supermemory

client = Supermemory(
    api_key=os.environ.get("SUPERMEMORY_API_KEY"),  # This is the default and can be omitted
)
response = client.profile(
    container_tag="containerTag",
)
print(response.profile)
{
  "profile": {
    "buckets": {
      "foo": [
        "string"
      ]
    },
    "dynamic": [
      "string"
    ],
    "static": [
      "string"
    ]
  },
  "searchResults": {
    "results": [
      {
        "id": "mem_abc123",
        "metadata": {
          "source": "bar",
          "confidence": "bar"
        },
        "similarity": 0.89,
        "updatedAt": "updatedAt",
        "chunk": "This is a chunk of content from a document...",
        "chunks": [
          {
            "content": "This is a chunk of content from the document...",
            "documentId": "doc_xyz789",
            "position": 0
          }
        ],
        "context": {
          "children": [
            {
              "memory": "Later version: API rate limit increased to 100 req/min on the free tier.",
              "relation": "extends",
              "updatedAt": "updatedAt",
              "metadata": {
                "foo": "bar"
              },
              "version": 1
            }
          ],
          "parents": [
            {
              "memory": "Earlier version: API rate limit is 50 req/min on the free tier.",
              "relation": "updates",
              "updatedAt": "updatedAt",
              "metadata": {
                "foo": "bar"
              },
              "version": -1
            }
          ],
          "related": [
            {
              "memory": "memory",
              "relation": "extends",
              "updatedAt": "updatedAt",
              "metadata": {
                "foo": "bar"
              }
            }
          ]
        },
        "documents": [
          {
            "id": "doc_xyz789",
            "createdAt": "createdAt",
            "updatedAt": "updatedAt",
            "metadata": {
              "source": "bar",
              "language": "bar"
            },
            "summary": "API rate limit policy: 100 req/min free, 1000 req/min pro.",
            "title": "API Rate Limiting Policy",
            "type": "web"
          }
        ],
        "filepath": "filepath",
        "isAggregated": false,
        "memory": "The user prefers detailed API responses over minimal ones.",
        "rootMemoryId": "mem_abc123",
        "version": 3
      }
    ],
    "timing": 0,
    "total": 0
  }
}
Returns Examples
{
  "profile": {
    "buckets": {
      "foo": [
        "string"
      ]
    },
    "dynamic": [
      "string"
    ],
    "static": [
      "string"
    ]
  },
  "searchResults": {
    "results": [
      {
        "id": "mem_abc123",
        "metadata": {
          "source": "bar",
          "confidence": "bar"
        },
        "similarity": 0.89,
        "updatedAt": "updatedAt",
        "chunk": "This is a chunk of content from a document...",
        "chunks": [
          {
            "content": "This is a chunk of content from the document...",
            "documentId": "doc_xyz789",
            "position": 0
          }
        ],
        "context": {
          "children": [
            {
              "memory": "Later version: API rate limit increased to 100 req/min on the free tier.",
              "relation": "extends",
              "updatedAt": "updatedAt",
              "metadata": {
                "foo": "bar"
              },
              "version": 1
            }
          ],
          "parents": [
            {
              "memory": "Earlier version: API rate limit is 50 req/min on the free tier.",
              "relation": "updates",
              "updatedAt": "updatedAt",
              "metadata": {
                "foo": "bar"
              },
              "version": -1
            }
          ],
          "related": [
            {
              "memory": "memory",
              "relation": "extends",
              "updatedAt": "updatedAt",
              "metadata": {
                "foo": "bar"
              }
            }
          ]
        },
        "documents": [
          {
            "id": "doc_xyz789",
            "createdAt": "createdAt",
            "updatedAt": "updatedAt",
            "metadata": {
              "source": "bar",
              "language": "bar"
            },
            "summary": "API rate limit policy: 100 req/min free, 1000 req/min pro.",
            "title": "API Rate Limiting Policy",
            "type": "web"
          }
        ],
        "filepath": "filepath",
        "isAggregated": false,
        "memory": "The user prefers detailed API responses over minimal ones.",
        "rootMemoryId": "mem_abc123",
        "version": 3
      }
    ],
    "timing": 0,
    "total": 0
  }
}