AI Logs API
The AI Logs API exposes superadmin-only observability for AI interactions, token usage, prompt replay, guardrail cost impact, and prompt-registry candidates.
All paths below are under /api/v1.0/admin/ai-logs. These endpoints require a superadmin session.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /admin/ai-logs | List AI interaction logs. |
GET | /admin/ai-logs/usage | Aggregate token and cost usage by date, model, and feature. |
GET | /admin/ai-logs/usage/people | Aggregate token and cost usage by user. |
GET | /admin/ai-logs/usage/guardrail-impact | Aggregate guardrail-driven repair, blocked-call, token, and cost impact. |
GET | /admin/ai-logs/{log_id} | Read one AI log with prompt trace and workflow-link detail. |
POST | /admin/ai-logs/{log_id}/replay | Replay a logged prompt or edited prompt through the governed replay path. |
POST | /admin/ai-logs/{log_id}/save-prompt | Save prompt content from a log as a new active prompt registry version. |
List AI Logs
GET /api/v1.0/admin/ai-logs?skip=0&limit=50&provider=openai&status=success&feature=copilot
Query Parameters
| Parameter | Type | Description |
|---|---|---|
skip | integer | Number of logs to skip. Default 0. |
limit | integer | Number of logs to return. Default 50. |
provider | string | Filter by provider. |
status | string | Filter by status, such as success, error, or blocked. |
feature | string | Filter by feature area, such as copilot, classification, or quality_suggestions. |
Response
{
"items": [
{
"id": "0d7a6c7c-5d42-4f9f-b75f-54e25598f0c9",
"instance_id": null,
"user_id": "67b1bc7e-90d4-4df0-b232-fbb6b947e8cf",
"provider": "openai",
"model_name": "gpt-4.1-mini",
"messages": [
{
"role": "user",
"content": "Summarize this product."
}
],
"response": "This product contains...",
"duration_ms": 1430,
"status": "success",
"prompt_tokens": 420,
"completion_tokens": 80,
"total_tokens": 500,
"cached_tokens": 0,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0,
"uncached_prompt_tokens": 420,
"feature": "copilot",
"estimated_cost": 0.0021,
"guardrail_metadata": null,
"budget_metadata": null,
"prompt_key": "catalog.product.summary",
"prompt_source": "registry",
"prompt_version_id": "5983173e-bef6-4c19-a9e9-b6d2e6f6f865",
"prompt_base_version_id": null,
"prompt_variation_version_id": null,
"prompt_provider": "openai",
"prompt_model_name": "gpt-4.1-mini",
"prompt_seed_hash": "a2d5f1",
"prompt_snapshot": "Summarize the product for a steward.",
"prompt_traces": [],
"replay_source_log_id": null,
"is_prompt_replay": false,
"workflow_run_count": 0,
"latest_workflow_run_id": null,
"latest_workflow_run_status": null,
"workflow_links": [],
"created_at": "2026-06-29T09:00:00Z"
}
],
"total": 1
}
Usage Summary
GET /api/v1.0/admin/ai-logs/usage?days=30
Returns usage grouped by date, model, and feature.
[
{
"date": "2026-06-29",
"model_name": "gpt-4.1-mini",
"feature": "copilot",
"total_prompt_tokens": 4200,
"total_completion_tokens": 900,
"total_tokens": 5100,
"call_count": 12,
"total_estimated_cost": 0.0215
}
]
Usage By Person
GET /api/v1.0/admin/ai-logs/usage/people?days=30
Returns usage grouped by triggering user. Logs without a user are grouped as System / unknown; deleted users are labeled Deleted user.
[
{
"user_id": "67b1bc7e-90d4-4df0-b232-fbb6b947e8cf",
"user_name": "Avery Steward",
"user_email": "avery@example.com",
"call_count": 42,
"total_prompt_tokens": 18000,
"total_completion_tokens": 6000,
"total_tokens": 24000,
"total_cached_tokens": 1200,
"total_cache_creation_input_tokens": 300,
"total_cache_read_input_tokens": 900,
"total_uncached_prompt_tokens": 16800,
"total_estimated_cost": 0.0842,
"last_used_at": "2026-06-29T09:00:00Z"
}
]
Guardrail Impact
GET /api/v1.0/admin/ai-logs/usage/guardrail-impact?days=30
Returns token and cost impact grouped by guardrail key, failure kind, and repair strategy. The aggregation includes logs with guardrail metadata and workflow validation repair signals.
[
{
"guardrail_key": "workflow_validation_repair",
"failure_kind": "validation_failed",
"repair_strategy": "structured_output_repair",
"affected_call_count": 8,
"repair_call_count": 5,
"blocked_call_count": 1,
"total_tokens": 18300,
"repair_tokens": 9100,
"total_estimated_cost": 0.0625,
"repair_estimated_cost": 0.0312
}
]
Get Log Detail
GET /api/v1.0/admin/ai-logs/{log_id}
The detail response includes the list fields plus prompt definition metadata, linked prompt versions, whether the prompt can be saved, and linked AI workflow runs.
{
"id": "0d7a6c7c-5d42-4f9f-b75f-54e25598f0c9",
"provider": "openai",
"model_name": "gpt-4.1-mini",
"status": "success",
"prompt_key": "catalog.product.summary",
"prompt_definition_name": "Catalog Product Summary",
"prompt_definition_description": "Summarizes a product for stewards.",
"prompt_code_seed_content": "Summarize the product for a steward.",
"prompt_version": {
"id": "5983173e-bef6-4c19-a9e9-b6d2e6f6f865",
"kind": "base",
"scope": "global",
"provider": "openai",
"model_name": "gpt-4.1-mini",
"content": "Summarize the product for a steward.",
"version_number": 4,
"status": "active",
"created_at": "2026-06-28T12:00:00Z"
},
"prompt_base_version": null,
"prompt_variation_version": null,
"can_save_prompt": true,
"workflow_runs": []
}
Replay A Log
POST /api/v1.0/admin/ai-logs/{log_id}/replay
Replay uses the source log's provider, model, messages, prompt snapshot, prompt registry metadata, and instance context unless overridden in the request. The replay is logged as a new AI log with is_prompt_replay: true and replay_source_log_id pointing to the original log.
Request Body
{
"messages": [
{
"role": "user",
"content": "Summarize this product in one sentence."
}
],
"prompt_snapshot": "Summarize the product for a steward in one sentence.",
"prompt_traces": [
{
"message_key": "catalog.product.summary.user",
"role": "user"
}
],
"provider": "openai",
"model_name": "gpt-4.1-mini",
"max_tokens": 1000,
"temperature": 0.3
}
| Field | Description |
|---|---|
messages | Optional replacement messages. Can be an array or an object containing messages or prompt. |
prompt_snapshot | Optional edited prompt text. Replaces the first system or user message for replay. |
prompt_traces | Optional prompt trace metadata to store on the replay log. |
provider, model_name | Optional replay provider/model overrides. |
max_tokens | Completion token cap. Default 1000, maximum 8000. |
temperature | Sampling temperature. Default 0.3, range 0 to 2. |
Response
{
"response": "A one-sentence summary...",
"ai_log_id": "1fc9fc86-eed2-4bd7-b763-c7e437d8cf40",
"provider": "openai",
"model_name": "gpt-4.1-mini",
"status": "success",
"duration_ms": 1180,
"prompt_tokens": 260,
"completion_tokens": 55,
"total_tokens": 315
}
Replay returns 400 when no valid replay messages can be built.
Save Prompt Candidate
POST /api/v1.0/admin/ai-logs/{log_id}/save-prompt
Creates and activates a prompt registry version from a log or edited prompt lab content. The source log must have a prompt registry key, unless prompt_key is supplied in the request.
Request Body
{
"kind": "base",
"scope": "global",
"prompt_key": "catalog.product.summary",
"message_key": "catalog.product.summary.user",
"provider": "openai",
"model_name": "gpt-4.1-mini",
"content": "Summarize the product for a steward in one sentence.",
"change_note": "Tightened product-summary prompt after replay."
}
| Field | Description |
|---|---|
kind | Prompt version kind, such as base or variation. |
scope | Prompt scope. Defaults to global; instance scope uses the source log instance. |
prompt_key | Optional prompt registry key. Falls back to the source log prompt key. |
message_key | Optional message key used to infer role from prompt traces and store a single-message prompt version. |
provider, model_name | Optional provider/model metadata for the prompt version. |
content | Required prompt content. |
change_note | Optional change note. Defaults to a log reference. |
Response
{
"prompt_key": "catalog.product.summary",
"version_id": "fb8ffb52-c664-4afd-a5e2-5a77989dc03d",
"kind": "base",
"version_number": 5
}
Errors
| Status | Description |
|---|---|
400 | Replay messages are missing, prompt save lacks a registry key, or prompt registry validation fails. |
401 | Authentication is missing or invalid. |
403 | Caller is not a superadmin. |
404 | AI log was not found. |
422 | Request body or query parameters failed validation. |