supermemory/apps/docs/overview/analytics.mdx

---
title: "Analytics & monitoring"
description: "Observe usage, errors, and logs to monitor your Supermemory integration"
icon: "/icons/hugeicons/chart-line-data-01.svg"
---

Monitor your Supermemory usage with detailed analytics on API calls, errors, and performance metrics.

## Overview

The Analytics API provides comprehensive insights into your Supermemory usage:

- **Usage Statistics**: Track API calls by type, hourly trends, and per-API key breakdown
- **Error Monitoring**: Identify top error types and patterns
- **Detailed Logs**: Inspect stored request logs and compacted response data for debugging
- **Performance Metrics**: Monitor average response times and processing duration

<Note>
Analytics data is available for your entire organization and can be filtered by time period.
</Note>

## Usage statistics

Get comprehensive usage statistics including hourly breakdowns and per-key metrics.

### Endpoint

`GET /v3/analytics/usage`

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `from` | string (ISO 8601) | Start date/time for the period |
| `to` | string (ISO 8601) | End date/time for the period |
| `period` | string | Alternative to `from`: `24h`, `7d`, `30d`, `all`. Use `from` and `to` for other windows |
| `page` | integer | Page number for pagination (default: 1) |
| `limit` | integer | Items per page (default: 20, max: 100) |

### Example request

<CodeGroup>

```typescript TypeScript
// Get usage for the last 24 hours
const usage = await fetch('https://api.supermemory.ai/v3/analytics/usage?period=24h', {
  headers: {
    'Authorization': `Bearer ${SUPERMEMORY_API_KEY}`
  }
});

const data = await usage.json();
```

```python Python
import requests
from datetime import datetime, timedelta

# Get usage for the last 7 days
response = requests.get(
    'https://api.supermemory.ai/v3/analytics/usage',
    params={'period': '7d'},
    headers={'Authorization': f'Bearer {SUPERMEMORY_API_KEY}'}
)

data = response.json()
```

```bash cURL
# Get usage for a specific date range
curl -X GET "https://api.supermemory.ai/v3/analytics/usage?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"
```

</CodeGroup>

### Response schema

```json
{
  "usage": [
    {
      "type": "add",
      "count": 1523,
      "avgDuration": 245.5,
      "lastUsed": "2024-01-15T14:30:00Z"
    },
    {
      "type": "search",
      "count": 3421,
      "avgDuration": 89.2,
      "lastUsed": "2024-01-15T14:35:00Z"
    }
  ],
  "hourly": [
    {
      "hour": "2024-01-15T14:00:00Z",
      "count": 156,
      "avgDuration": 125.3
    }
  ],
  "byKey": [
    {
      "keyId": "key_abc123",
      "keyName": "Production API",
      "count": 2341,
      "avgDuration": 98.7,
      "lastUsed": "2024-01-15T14:35:00Z",
      "tokensUsed": 182340
    }
  ],
  "totalMemories": 45678,
  "pagination": {
    "currentPage": 1,
    "limit": 20,
    "totalItems": 150,
    "totalPages": 8
  }
}
```

`tokensUsed` sums recorded `finalTokens` for the listed keys, including chat usage. It is not the billable ingestion-token meter, and ordinary memory request logs do not necessarily populate it.

## Error monitoring

Track and analyze errors to identify issues and improve reliability.

### Endpoint

`GET /v3/analytics/errors`

### Parameters

Same as usage endpoint - supports `from`, `to`, `period`, `page`, and `limit`.

### Example request

<CodeGroup>

```typescript TypeScript
// Get errors from the last 24 hours
const errors = await fetch('https://api.supermemory.ai/v3/analytics/errors?period=24h', {
  headers: {
    'Authorization': `Bearer ${SUPERMEMORY_API_KEY}`
  }
});

const data = await errors.json();
```

```python Python
# Monitor errors and alert on spikes
response = requests.get(
    'https://api.supermemory.ai/v3/analytics/errors?period=24h',
    headers={'Authorization': f'Bearer {SUPERMEMORY_API_KEY}'}
)

data = response.json()
```

```bash cURL
# Get errors for the last 7 days
curl -X GET "https://api.supermemory.ai/v3/analytics/errors?period=7d" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"
```

</CodeGroup>

### Response schema

```json
{
  "summary": [
    {
      "type": "search_v4",
      "totalRequests": 3421,
      "successRate": 97.4,
      "errorRate": 2.6,
      "lastRequest": "2024-01-15T14:35:00Z"
    }
  ],
  "errors": [
    {
      "type": "search_v4",
      "statusCode": 400,
      "count": 89,
      "percentage": 100
    }
  ],
  "hourly": [
    {
      "hour": "2024-01-15T14:00:00Z",
      "count": 156,
      "errorCount": 4,
      "errorRate": 2.56
    }
  ],
  "byKey": [
    {
      "keyId": "key_abc123",
      "keyName": "Production API",
      "count": 2341,
      "errorCount": 61,
      "errorRate": 2.61,
      "lastUsed": "2024-01-15T14:35:00Z"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "limit": 20,
    "totalItems": 3421,
    "totalPages": 172
  }
}
```

## Detailed logs

Inspect stored request logs for debugging. Response data is compacted: strings, arrays, fields, and nesting can be truncated. The ordinary request tracker skips HTTP `402`, `404`, and `500` responses, so this is not a complete audit trail.

### Endpoint

`GET /v3/analytics/logs`

### Parameters

Use `from`, `to`, `period`, `page`, and `limit` as above. The current `/logs` handler filters by organization and time only; it does not apply `type`, `statusCode`, or `keyId` filters.

### Example request

<CodeGroup>

```typescript TypeScript
const logs = await fetch('https://api.supermemory.ai/v3/analytics/logs?period=24h', {
  headers: {
    'Authorization': `Bearer ${SUPERMEMORY_API_KEY}`
  }
});

const data = await logs.json();
```

```python Python
response = requests.get(
    'https://api.supermemory.ai/v3/analytics/logs',
    params={
        'period': '24h'
    },
    headers={'Authorization': f'Bearer {SUPERMEMORY_API_KEY}'}
)

logs = response.json()['logs']

```

```bash cURL
# Get all logs for debugging
curl -X GET "https://api.supermemory.ai/v3/analytics/logs?period=24h&limit=50" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"
```

</CodeGroup>

### Response schema

```json
{
  "logs": [
    {
      "id": "req_xyz789",
      "createdAt": "2024-01-15T14:30:00Z",
      "type": "search",
      "statusCode": 200,
      "duration": 89,
      "input": "{\"q\":\"user query\",\"limit\":10}",
      "output": {
        "type": "search",
        "response": { "results": [], "timing": 85, "total": 0 }
      }
    }
  ],
  "pagination": {
    "currentPage": 1,
    "limit": 20,
    "totalItems": 500,
    "totalPages": 25
  }
}
```

## Limits and retention

The maximum page size is 100 items. Normal API request rate limits also apply; this page does not establish a separate analytics-specific allowance.

<Warning>
An accepted date range does not guarantee that historical logs are still retained. Confirm the applicable service retention policy with Supermemory, and export data to your own systems when you need longer retention.
</Warning>