Skip to main content
POST
/
api
/
request-logs
/
summary
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())

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

Documentation Index

Fetch the complete documentation index at: https://docs.keywordsai.co/llms.txt

Use this file to discover all available pages before exploring further.

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.
{
  "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.
{
  "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.
  {
    "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:
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
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())

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

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

# 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']}")