Requests API

Query and analyze request logs programmatically.

Endpoints

List Requests

GET /v1/requests

List all requests with filtering and pagination.

Parameters:

Parameter	Type	Description
limit	integer	Results per page (default: 20, max: 100)
cursor	string	Pagination cursor
prompt_name	string	Filter by prompt name
status	string	Filter by status (success, error)
start_date	string	Start date (ISO 8601)
end_date	string	End date (ISO 8601)
metadata	object	Filter by metadata

Response:

{
  "data": [
    {
      "id": "req_abc123",
      "prompt_name": "customer-classifier",
      "version": 3,
      "status": "success",
      "input_variables": {
        "message": "I need help"
      },
      "output": {
        "category": "general"
      },
      "metadata": {
        "user_id": "user_123"
      },
      "usage": {
        "total_tokens": 60,
        "estimated_cost_usd": 0.0012
      },
      "latency_ms": 1234,
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "xyz789"
  }
}

Get Request

GET /v1/requests/{request_id}

Get details for a specific request.

Response:

{
  "data": {
    "id": "req_abc123",
    "prompt_name": "customer-classifier",
    "version": 3,
    "status": "success",
    "input_variables": {
      "message": "I need help with billing"
    },
    "output": {
      "category": "billing",
      "confidence": 0.95
    },
    "metadata": {
      "user_id": "user_123",
      "session_id": "session_456",
      "environment": "production"
    },
    "model": "gpt-4",
    "usage": {
      "prompt_tokens": 50,
      "completion_tokens": 10,
      "total_tokens": 60,
      "estimated_cost_usd": 0.0012
    },
    "timing": {
      "total_latency_ms": 1234,
      "pre_process_ms": 50,
      "llm_call_ms": 1100,
      "post_process_ms": 84
    },
    "integration": {
      "pre_process_executed": true,
      "post_process_executed": true,
      "errors": []
    },
    "created_at": "2025-01-15T10:00:00Z"
  }
}

Search Requests

GET /v1/requests/search

Search requests by content.

Parameters:

Parameter	Type	Description
query	string	Search query
limit	integer	Results per page
cursor	string	Pagination cursor

Response:

{
  "data": [
    {
      "id": "req_abc123",
      "prompt_name": "classifier",
      "matched_fields": ["input_variables.message", "output"],
      "highlights": {
        "input_variables.message": "I need help with <em>billing</em>"
      },
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "has_more": false
  }
}

Export Requests

POST /v1/requests/export

Export requests to CSV or JSON.

Request:

{
  "format": "csv",
  "filters": {
    "prompt_name": "classifier",
    "start_date": "2025-01-01",
    "end_date": "2025-01-31"
  },
  "include_metadata": true
}

Response:

{
  "data": {
    "export_id": "export_abc123",
    "status": "processing",
    "download_url": null,
    "created_at": "2025-01-15T10:00:00Z"
  }
}

Check export status:

GET /v1/requests/exports/{export_id}

Delete Requests

DELETE /v1/requests

Delete requests matching criteria (GDPR compliance).

Request:

{
  "metadata": {
    "user_id": "user_123"
  }
}

Response:

{
  "data": {
    "deleted_count": 156,
    "deleted_at": "2025-01-15T10:00:00Z"
  }
}

Analytics

Get Request Analytics

GET /v1/requests/analytics

Get aggregated analytics for requests.

Parameters:

Parameter	Type	Description
metric	string	Metric to query (cost, usage, latency, errors)
group_by	string	Group by field
start_date	string	Start date
end_date	string	End date
filters	object	Additional filters

Response:

{
  "data": {
    "metric": "cost",
    "total": 125.50,
    "groups": [
      {
        "name": "customer-classifier",
        "value": 45.30,
        "count": 5432
      },
      {
        "name": "content-generator",
        "value": 80.20,
        "count": 3210
      }
    ],
    "period": {
      "start": "2025-01-01T00:00:00Z",
      "end": "2025-01-31T23:59:59Z"
    }
  }
}

Examples

Python SDK

from mandatum import Mandatum
from datetime import datetime, timedelta

client = Mandatum(api_key="your-api-key")

# List recent requests
requests = client.requests.list(
    limit=50,
    start_date=(datetime.now() - timedelta(days=7)).isoformat()
)

for req in requests:
    print(f"{req.created_at}: {req.prompt_name} - {req.status}")

# Filter by metadata
requests = client.requests.list(
    metadata={"user_id": "user_123"}
)

# Search
results = client.requests.search(
    query="billing issue"
)

# Get specific request
request = client.requests.get("req_abc123")
print(f"Latency: {request.timing.total_latency_ms}ms")
print(f"Cost: ${request.usage.estimated_cost_usd:.4f}")

# Export
export = client.requests.export(
    format="csv",
    filters={
        "prompt_name": "classifier",
        "start_date": "2025-01-01",
        "end_date": "2025-01-31"
    }
)

# Check export status
status = client.requests.get_export_status(export.export_id)
if status.status == "completed":
    print(f"Download: {status.download_url}")

# GDPR: Delete user data
client.requests.delete(
    metadata={"user_id": "user_123"}
)

# Analytics
analytics = client.requests.get_analytics(
    metric="cost",
    group_by="prompt_name",
    start_date="2025-01-01",
    end_date="2025-01-31"
)

print(f"Total cost: ${analytics.total:.2f}")
for group in analytics.groups:
    print(f"  {group.name}: ${group.value:.2f}")

TypeScript SDK

Coming Soon

A TypeScript/JavaScript SDK is in development. For now, use the REST API directly.

cURL

# List requests
curl -X GET "https://mandatum-api.gavelinivar.com/api/v1/requests?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by metadata
curl -X GET "https://mandatum-api.gavelinivar.com/api/v1/requests?metadata.user_id=user_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Search
curl -X GET "https://mandatum-api.gavelinivar.com/api/v1/requests/search?query=billing" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get request
curl -X GET "https://mandatum-api.gavelinivar.com/api/v1/requests/req_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Export
curl -X POST "https://mandatum-api.gavelinivar.com/api/v1/requests/export" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "filters": {
      "start_date": "2025-01-01",
      "end_date": "2025-01-31"
    }
  }'

See Also

• Logging Guide
• Analytics Guide
• Metadata Documentation