Get logs summary

POST /api/request-logs/summary/

Python

import requests

url = "https://api.keywordsai.co/api/request-logs/summary/"
headers = {
    "Authorization": f"Bearer {YOUR_KEYWORDS_AI_API_KEY}",
    "Content-Type": "application/json"
}
params = {
    "start_time": "2025-12-01T00:00:00Z",
    "end_time": "2025-12-31T23:59:59Z"
}
data = {
    "filters": {
        "model": {
            "operator": "",
            "value": ["gpt-4o"]
        }
    }
}

response = requests.post(url, headers=headers, params=params, json=data)
print(response.json())

200 OK

{
  "total_cost": 15.67,
  "total_tokens": 1250000,
  "number_of_requests": 8453,
  "scores": {
    "550e8400-e29b-41d4-a716-446655440000": {
      "evaluator_id": "550e8400-e29b-41d4-a716-446655440000",
      "evaluator_slug": "quality_v1",
      "evaluator_name": "Response Quality",
      "score_value_type": "numerical",
      "avg_score": 4.2,
      "true_count": null,
      "false_count": null
    },
    "661e9511-f3ab-52e5-b827-557766551111": {
      "evaluator_id": "661e9511-f3ab-52e5-b827-557766551111",
      "evaluator_slug": "accuracy_v1",
      "evaluator_name": "Factual Accuracy",
      "score_value_type": "boolean",
      "avg_score": null,
      "true_count": 150,
      "false_count": 10
    }
  }
}

The Logs Summary endpoint returns aggregated statistics for logs matching the given filters. This is useful for getting quick insights into your LLM usage without fetching all individual logs.

Both GET and POST methods are supported. POST is recommended when using complex filters.

Query parameters

Same parameters as the List Logs endpoint:

start_time · string

The start time for filtering logs in ISO 8601 format. If not provided, defaults to 1 hour ago.

Example

{
  "start_time": "2025-08-15T00:00:00Z"
}

end_time · string

The end time for filtering logs in ISO 8601 format. If not provided, defaults to current time.

Example

{
  "end_time": "2025-08-16T00:00:00Z"
}

all_envs · string · default: "false"

Whether to include logs from all environments. is_test parameter will override this parameter. Options: true, false.

is_test · string · default: "false"

Whether to include test logs only. This parameter will override the all_envs parameter. Options: true, false.

Body parameters

You can add filter parameters to the request body (same as List Logs endpoint):

filters · object

The filters to be applied to the logs.

If you want to filter your custom properties, add metadata__ + your custom property name. For example, to filter my_custom_property, use metadata__my_custom_property.

For a complete list of filter operators and examples, see the Filters API Reference.

Example

  {
    "model": {
      "operator": "",
      "value": ["gpt-4o"]
    },
    "cost": {
      "operator": "gte",
      "value": [0.01]
    }
  }

URL-based Filtering

Just like the List Logs endpoint, you can use URL parameters for quick filtering:

# Filter summary by customer
GET /api/request-logs/summary/?customer_identifier=user_123

# Filter by custom metadata
GET /api/request-logs/summary/?user_tier=premium&department=sales

See the List Logs endpoint for complete URL filtering documentation.

Response

All fields are returned at the top level (consistent with experiments API format):

total_cost · float

Total cost in USD for all filtered logs.

total_tokens · integer

Total tokens (prompt + completion) for all filtered logs.

number_of_requests · integer

Total number of requests matching the filters.

scores · object

Aggregated score summaries grouped by evaluator_id. Each evaluator includes:

Show Score Summary Fields

evaluator_id · string

UUID of the evaluator

evaluator_slug · string

URL-friendly identifier for the evaluator

evaluator_name · string

Display name of the evaluator

score_value_type · string

Type of score: "numerical", "percentage", or "boolean"

avg_score · float | null

Average score for numerical/percentage evaluators. null for boolean evaluators.

true_count · integer | null

Count of true values for boolean evaluators. null for numerical/percentage evaluators.

false_count · integer | null

Count of false values for boolean evaluators. null for numerical/percentage evaluators.

Score Type Behavior:

• Numerical/Percentage evaluators: Only avg_score is populated
• Boolean evaluators: Only true_count and false_count are populated
• Other types: String, categorical, and JSON evaluators are not included in aggregations

Python

import requests

url = "https://api.keywordsai.co/api/request-logs/summary/"
headers = {
    "Authorization": f"Bearer {YOUR_KEYWORDS_AI_API_KEY}",
    "Content-Type": "application/json"
}
params = {
    "start_time": "2025-12-01T00:00:00Z",
    "end_time": "2025-12-31T23:59:59Z"
}
data = {
    "filters": {
        "model": {
            "operator": "",
            "value": ["gpt-4o"]
        }
    }
}

response = requests.post(url, headers=headers, params=params, json=data)
print(response.json())

200 OK

{
  "total_cost": 15.67,
  "total_tokens": 1250000,
  "number_of_requests": 8453,
  "scores": {
    "550e8400-e29b-41d4-a716-446655440000": {
      "evaluator_id": "550e8400-e29b-41d4-a716-446655440000",
      "evaluator_slug": "quality_v1",
      "evaluator_name": "Response Quality",
      "score_value_type": "numerical",
      "avg_score": 4.2,
      "true_count": null,
      "false_count": null
    },
    "661e9511-f3ab-52e5-b827-557766551111": {
      "evaluator_id": "661e9511-f3ab-52e5-b827-557766551111",
      "evaluator_slug": "accuracy_v1",
      "evaluator_name": "Factual Accuracy",
      "score_value_type": "boolean",
      "avg_score": null,
      "true_count": 150,
      "false_count": 10
    }
  }
}

Use Cases

Monitor monthly costs

# Get total cost for the current month
import requests
from datetime import datetime

start_of_month = datetime.now().replace(day=1, hour=0, minute=0, second=0).isoformat() + "Z"

response = requests.get(
    "https://api.keywordsai.co/api/request-logs/summary/",
    headers={"Authorization": f"Bearer {YOUR_API_KEY}"},
    params={
        "start_time": start_of_month,
        "environment": "prod"
    }
)

data = response.json()
print(f"Monthly cost: ${data['total_cost']:.2f}")
print(f"Total requests: {data['number_of_requests']}")

# Access score summaries
if "scores" in data:
    for evaluator_id, score_data in data["scores"].items():
        print(f"{score_data['evaluator_name']}: avg={score_data.get('avg_score', 'N/A')}")

Compare model costs

# Compare costs between different models
models = ["gpt-4o", "gpt-4o-mini", "claude-3-5-sonnet-20241022"]

for model in models:
    response = requests.post(
        "https://api.keywordsai.co/api/request-logs/summary/",
        headers={"Authorization": f"Bearer {YOUR_API_KEY}"},
        json={
            "filters": {
                "model": {
                    "operator": "",
                    "value": [model]
                }
            }
        }
    )
    data = response.json()
    print(f"{model}: ${data['total_cost']:.2f}")

Track customer usage

# Get summary for a specific customer
response = requests.get(
    "https://api.keywordsai.co/api/request-logs/summary/",
    headers={"Authorization": f"Bearer {YOUR_API_KEY}"},
    params={
        "customer_identifier": "customer_123",
        "start_time": "2025-12-01T00:00:00Z"
    }
)

data = response.json()
print(f"Customer cost: ${data['total_cost']:.2f}")
print(f"Customer requests: {data['number_of_requests']}")