supermemory/apps/docs/user-profiles/api.mdx

---
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 |
| `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>

## Error Responses

| Status | Description |
|--------|-------------|
| `400` | Missing or invalid `containerTag` |
| `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>