Skip to main content
POST
https://api.respan.ai
/
api
/
request-logs
/
summary
import requests

url = "https://api.respan.ai/api/request-logs/summary/"
headers = {
    "Authorization": f"Bearer {YOUR_RESPAN_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
    }
  }
}
The Spans Summary endpoint returns aggregated statistics for spans matching the given filters. This is useful for getting quick insights into your LLM usage without fetching all individual spans.
Both GET and POST methods are supported. POST is recommended when using complex filters.

​
Query parameters

Same parameters as the List spans endpoint:
​
start_time
string
The start time for filtering spans 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 spans 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 spans from all environments. is_test parameter will override this parameter. Options: true, false.
​
is_test
string
default:"false"
Whether to include test spans 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 spans endpoint):
​
filters
object
The filters to be applied to the spans.
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 spans 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 spans 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 spans.
​
total_tokens
integer
Total tokens (prompt + completion) for all filtered spans.
​
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.respan.ai/api/request-logs/summary/"
headers = {
    "Authorization": f"Bearer {YOUR_RESPAN_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.respan.ai/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.respan.ai/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.respan.ai/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']}")