Profile API - Supermemory

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

json

{
  "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);

python

import requests
import os

response = requests.post(
    'https://api.supermemory.ai/v4/profile',
    headers={
        'Authorization': f'Bearer {os.getenv("SUPERMEMORY_API_KEY")}',
        'Content-Type': 'application/json'
    },
    json={
        'containerTag': 'user_123'
    }
)

data = response.json()

print("Static facts:", data['profile']['static'])
print("Dynamic context:", data['profile']['dynamic'])

bash

curl -X POST https://api.supermemory.ai/v4/profile \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "containerTag": "user_123"
  }'

</CodeGroup>

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 || [];

python

response = requests.post(
    'https://api.supermemory.ai/v4/profile',
    headers={
        'Authorization': f'Bearer {os.getenv("SUPERMEMORY_API_KEY")}',
        'Content-Type': 'application/json'
    },
    json={
        'containerTag': 'user_123',
        'q': 'deployment errors yesterday'
    }
)

data = response.json()

profile = data['profile']
search_results = data.get('searchResults', {}).get('results', [])

</CodeGroup>

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();

python

response = requests.post(
    'https://api.supermemory.ai/v4/profile',
    headers={
        'Authorization': f'Bearer {os.getenv("SUPERMEMORY_API_KEY")}',
        'Content-Type': 'application/json'
    },
    json={
        'containerTag': 'user_123',
        'threshold': 0.7,  # Only include results with score > 0.7
        'q': 'deployment errors yesterday'
    }
)

data = response.json()

</CodeGroup>

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.

<Card title="See Examples" icon="laptop-code" href="/user-profiles/examples"> View complete integration examples for chat apps, support systems, and more </Card>