Analytics & monitoring

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

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

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

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

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

# 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"

Response schema

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

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

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

# 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"

Response schema

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

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

const data = await logs.json();

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

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

# 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"

Response schema

{
  "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.

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.

Getting started

Concepts

Using supermemory

Deployment

Other resources

Migration guides

Overview

Usage statistics

Endpoint

Parameters

Example request

Response schema

Error monitoring

Endpoint

Parameters

Example request

Response schema

Detailed logs

Endpoint

Parameters

Example request

Response schema

Limits and retention

​Overview

​Usage statistics

​Endpoint

​Parameters

​Example request

​Response schema

​Error monitoring

​Endpoint

​Parameters

​Example request

​Response schema

​Detailed logs

​Endpoint

​Parameters

​Example request

​Response schema

​Limits and retention

Overview

Usage statistics

Endpoint

Parameters

Example request

Response schema

Error monitoring

Endpoint

Parameters

Example request

Response schema

Detailed logs

Endpoint

Parameters

Example request

Response schema

Limits and retention