Monitoring & Health

Monitor system health, track usage metrics, export data, and manage billing analytics.

Public Health Check

Simple health check endpoint. No authentication required.

GET /health

Code Examples

cURL

curl https://api.engrammemory.ai/health

Python

import requests

response = requests.get("https://api.engrammemory.ai/health")
print(response.json())

JavaScript

const response = await fetch("https://api.engrammemory.ai/health");
const health = await response.json();
console.log(health);

Response

{
  "status": "healthy",
  "timestamp": "2026-04-10T14:30:00Z"
}

---

Detailed Health Check

Authenticated health check with per-service status.

GET /v1/health

Code Examples

cURL

curl https://api.engrammemory.ai/v1/health \
  -H "Authorization: Bearer pr_live_xxxxx"

Python

from engrammemory import Engram

client = Engram(api_key="pr_live_xxxxx")

health = client.health()
print(f"Status: {health.status}")
for service, status in health.services.items():
    print(f"  {service}: {status}")

JavaScript

import { Engram } from "engrammemory-ai";

const client = new Engram({ apiKey: "pr_live_xxxxx" });

const health = await client.health();
console.log(`Status: ${health.status}`);
Object.entries(health.services).forEach(([service, status]) => {
  console.log(`  ${service}: ${status}`);
});

Response

{
  "status": "healthy",
  "version": "1.8.2",
  "environment": "production",
  "uptime_seconds": 1296000,
  "services": {
    "api": "healthy",
    "embedding": "healthy",
    "vector_db": "healthy"
  },
  "timestamp": "2026-04-10T14:30:00Z"
}

Response Fields

---

System Metrics

Get comprehensive system metrics including request rates, response times, and usage.

GET /v1/monitoring/metrics

Code Examples

cURL

curl https://api.engrammemory.ai/v1/monitoring/metrics \
  -H "Authorization: Bearer pr_live_xxxxx"

Python

metrics = client.monitoring.metrics()
print(f"Requests (24h): {metrics.requests_24h}")
print(f"Error rate: {metrics.error_rate_pct}%")
print(f"Avg response time: {metrics.avg_response_time_ms} ms")

JavaScript

const metrics = await client.monitoring.metrics();
console.log(`Requests (24h): ${metrics.requests24h}`);
console.log(`Error rate: ${metrics.errorRatePct}%`);
console.log(`Avg response time: ${metrics.avgResponseTimeMs} ms`);

Response

{
  "uptime_seconds": 1296000,
  "requests": {
    "total_24h": 245000,
    "total_7d": 1520000,
    "rate_per_minute": 170.1
  },
  "response_time": {
    "avg_ms": 42,
    "p50_ms": 28,
    "p95_ms": 120,
    "p99_ms": 340
  },
  "error_rate_pct": 0.12,
  "errors": {
    "4xx_24h": 180,
    "5xx_24h": 14
  },
  "active_users": {
    "daily": 1240,
    "weekly": 4800,
    "monthly": 12000
  },
  "usage": {
    "total_memories": 8500000,
    "total_collections": 42000,
    "storage_used_gb": 124.5,
    "embeddings_generated_24h": 85000,
    "searches_24h": 62000
  },
  "service_health": {
    "api": { "status": "healthy", "latency_ms": 12 },
    "embedding": { "status": "healthy", "latency_ms": 35 },
    "vector_db": { "status": "healthy", "latency_ms": 8 }
  },
  "timestamp": "2026-04-10T14:30:00Z"
}

---

Export Usage Data

Export usage data for a specified time range.

POST /v1/export/usage

Request Body

Code Examples

cURL

curl -X POST https://api.engrammemory.ai/v1/export/usage \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2026-03-01T00:00:00Z",
    "end_date": "2026-03-31T23:59:59Z",
    "format": "CSV"
  }'

Python

export = client.export.usage(
    start_date="2026-03-01T00:00:00Z",
    end_date="2026-03-31T23:59:59Z",
    format="CSV",
)
print(f"Export job: {export.job_id}")
print(f"Download: {export.download_url}")

JavaScript

const exportJob = await client.export.usage({
  startDate: "2026-03-01T00:00:00Z",
  endDate: "2026-03-31T23:59:59Z",
  format: "CSV",
});
console.log(`Export job: ${exportJob.jobId}`);
console.log(`Download: ${exportJob.downloadUrl}`);

Response

{
  "job_id": "exp_usage_abc123",
  "status": "COMPLETED",
  "format": "CSV",
  "start_date": "2026-03-01T00:00:00Z",
  "end_date": "2026-03-31T23:59:59Z",
  "file_size_bytes": 245000,
  "download_url": "https://api.engrammemory.ai/v1/export/exp_usage_abc123/download",
  "expires_at": "2026-04-10T15:30:00Z",
  "created_at": "2026-04-10T14:30:00Z"
}

---

Billing Analytics

Get billing and usage analytics for cost monitoring.

POST /v1/analytics/billing

Request Body

Code Examples

cURL

curl -X POST https://api.engrammemory.ai/v1/analytics/billing \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "include_operations": true,
    "months_back": 3
  }'

Python

billing = client.analytics.billing(include_operations=True, months_back=3)
print(f"Current month cost: ${billing.current_month.total_cost}")
for op in billing.current_month.operations:
    print(f"  {op.name}: {op.count} calls, ${op.cost}")

JavaScript

const billing = await client.analytics.billing({
  includeOperations: true,
  monthsBack: 3,
});
console.log(`Current month cost: $${billing.currentMonth.totalCost}`);
billing.currentMonth.operations.forEach((op) => {
  console.log(`  ${op.name}: ${op.count} calls, $${op.cost}`);
});

Response

{
  "plan": "pro",
  "billing_period": "2026-04-01 to 2026-04-30",
  "current_month": {
    "total_cost": 48.50,
    "memories_stored": 125000,
    "searches_performed": 62000,
    "embeddings_generated": 85000,
    "storage_gb": 12.4,
    "operations": [
      { "name": "memory_store", "count": 125000, "cost": 12.50 },
      { "name": "memory_search", "count": 62000, "cost": 18.60 },
      { "name": "embedding_generate", "count": 85000, "cost": 8.50 },
      { "name": "storage", "count": null, "cost": 8.90, "unit": "12.4 GB" }
    ]
  },
  "history": [
    {
      "month": "2026-03",
      "total_cost": 42.30,
      "memories_stored": 110000,
      "searches_performed": 55000
    },
    {
      "month": "2026-02",
      "total_cost": 38.10,
      "memories_stored": 98000,
      "searches_performed": 48000
    }
  ]
}

---

Data Export

Export your memories and data in multiple formats for backup or migration.

POST /v1/export

Request Body

Export Formats

Code Examples

cURL

curl -X POST https://api.engrammemory.ai/v1/export \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "ENGRAM_JSON",
    "collections": ["col_abc123"],
    "include_vectors": true,
    "include_metadata": true
  }'

Python

export = client.export.create(
    format="ENGRAM_JSON",
    collections=["col_abc123"],
    include_vectors=True,
    include_metadata=True,
)
print(f"Export job: {export.job_id}")
# Poll for completion
status = client.export.get(export.job_id)
if status.status == "COMPLETED":
    print(f"Download: {status.download_url}")

JavaScript

const exportJob = await client.export.create({
  format: "ENGRAM_JSON",
  collections: ["col_abc123"],
  includeVectors: true,
  includeMetadata: true,
});
console.log(`Export job: ${exportJob.jobId}`);
// Poll for completion
const status = await client.export.get(exportJob.jobId);
if (status.status === "COMPLETED") {
  console.log(`Download: ${status.downloadUrl}`);
}

Response

{
  "job_id": "exp_abc123",
  "status": "PROCESSING",
  "format": "ENGRAM_JSON",
  "collections": ["col_abc123"],
  "include_vectors": true,
  "include_metadata": true,
  "memories_count": null,
  "file_size_bytes": null,
  "download_url": null,
  "progress_pct": 0,
  "created_at": "2026-04-10T14:30:00Z",
  "completed_at": null,
  "expires_at": null
}

---

Get Export Job Status

Check the status of an export job and get the download URL when complete.

GET /v1/export/{job_id}

Path Parameters

Code Examples

cURL

curl https://api.engrammemory.ai/v1/export/exp_abc123 \
  -H "Authorization: Bearer pr_live_xxxxx"

Python

status = client.export.get("exp_abc123")
print(f"Status: {status.status}")
print(f"Progress: {status.progress_pct}%")
if status.download_url:
    print(f"Download: {status.download_url}")

JavaScript

const status = await client.export.get("exp_abc123");
console.log(`Status: ${status.status}`);
console.log(`Progress: ${status.progressPct}%`);
if (status.downloadUrl) {
  console.log(`Download: ${status.downloadUrl}`);
}

Response (Completed)

{
  "job_id": "exp_abc123",
  "status": "COMPLETED",
  "format": "ENGRAM_JSON",
  "collections": ["col_abc123"],
  "memories_count": 8420,
  "file_size_bytes": 15200000,
  "download_url": "https://api.engrammemory.ai/v1/export/exp_abc123/download",
  "progress_pct": 100,
  "created_at": "2026-04-10T14:30:00Z",
  "completed_at": "2026-04-10T14:32:15Z",
  "expires_at": "2026-04-11T14:32:15Z"
}

Export Job Statuses

---

Error Codes