1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
|
---
title: "Profile API"
description: "Endpoint details and response structure for user profiles"
sidebarTitle: "API Reference"
icon: "code"
---
## 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
<CodeGroup>
```typescript 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 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
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:
<CodeGroup>
```typescript 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 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:
<CodeGroup>
```typescript 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 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>
|