Profile API

Endpoint details and response structure for user profiles

Endpoint

POST /v4/profile

Retrieves a user’s profile, optionally combined with search results.

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer token with your API key
Content-Type	Yes	application/json

Body Parameters

Parameter	Type	Required	Description
containerTag	string	Yes	The container tag (usually user ID) to get profiles for
threshold	float	No	Threshold for filtering search results. Only results with a score above this threshold will be included.
q	string	No	Optional search query to include search results with the profile

Response

{
  "profile": {
    "static": [
      "User is a software engineer",
      "User specializes in Python and React",
      "User prefers dark mode interfaces"
    ],
    "dynamic": [
      "User is working on Project Alpha",
      "User recently started learning Rust",
      "User is debugging authentication issues"
    ]
  },
  "searchResults": {
    "results": [...],  // Only if 'q' parameter was provided
    "total": 15,
    "timing": 45.2
  }
}

Response Fields

Field	Type	Description
profile.static	string[]	Long-term, stable facts about the user
profile.dynamic	string[]	Recent context and temporary information
searchResults	object	Only present if q parameter was provided
searchResults.results	array	Matching memory results
searchResults.total	number	Total number of matches
searchResults.timing	number	Query execution time in milliseconds

Basic Request

TypeScript

const response = await fetch('https://api.supermemory.ai/v4/profile', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    containerTag: 'user_123'
  })
});

const data = await response.json();

console.log("Static facts:", data.profile.static);
console.log("Dynamic context:", data.profile.dynamic);

Profile with Search

Include a search query to get both profile data and relevant memories in one call:

TypeScript

const response = await fetch('https://api.supermemory.ai/v4/profile', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    containerTag: 'user_123',
    q: 'deployment errors yesterday'
  })
});

const data = await response.json();

// Profile data
const profile = data.profile;

// Search results (only present because we passed 'q')
const searchResults = data.searchResults?.results || [];

Profile with Threshold

Use the optional threshold parameter to filter search results by relevance score:

TypeScript

const response = await fetch('https://api.supermemory.ai/v4/profile', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    containerTag: 'user_123',
    threshold: 0.7,  // Only include results with score > 0.7
    q: 'deployment errors yesterday'
  })
});

const data = await response.json();

Error Responses

Status	Description
400	Missing or invalid containerTag or threshold
401	Invalid or missing API key
404	Container not found
500	Internal server error

Rate Limits

Profile requests count toward your standard API rate limits. Since profiles are cached, repeated requests for the same user are efficient.

See Examples

View complete integration examples for chat apps, support systems, and more