List logs

Retrieve log entries with pagination and sorting using URL query parameters

Overview

The list() and alist() methods allow you to retrieve multiple log entries using URL query parameters. Use list() for synchronous operations and alist() for asynchronous operations.

Usage example

from keywordsai.logs.api import LogAPI
import asyncio

# Create the client
log_api_client = LogAPI()

# Synchronous example
response = log_api_client.list(page_size=50)
print(f"Retrieved {len(response.results)} logs")
for log in response.results:
    print(f"Log {log.unique_id}: {log.model}")

# Asynchronous example
async def list_logs_async():
    response = await log_api_client.alist(page_size=50)
    print(f"Retrieved {len(response.results)} logs asynchronously")
    return response.results

# Run the async function
asyncio.run(list_logs_async())

Parameters

page · int · default: "1"

The page number to retrieve.

page_size · int · default: "100"

Number of logs to return per page (maximum: 1000).

sort_by · str · default: "-id"

Field to sort by. Use - prefix for descending order. Available options: id, cost, latency, prompt_tokens, completion_tokens, all_tokens, time_to_first_token

is_test · str · default: "false"

Whether to include test logs. Options: "true", "false".

all_envs · str · default: "false"

Whether to include logs from all environments. Options: "true", "false".

Returns

Returns a LogListResponse object with:

{
    "results": [
        {
            "id": "log_123456789",
            "unique_id": "unique_123",
            "model": "gpt-4",
            "prompt_tokens": 20,
            "completion_tokens": 50,
            "total_tokens": 70,
            "cost": 0.0014,
            "latency": 1.2,
            "timestamp": "2024-01-15T10:30:00Z",
            "metadata": {...}
        },
        ...
    ],
    "count": 150,
    "next": "...",
    "previous": "..."
}

Examples

Basic Synchronous Example

import os
from dotenv import load_dotenv
from keywordsai.logs.api import LogAPI

load_dotenv()

def list_logs_sync():
    """Basic synchronous log listing"""
    api_key = os.getenv("KEYWORDS_AI_API_KEY")
    log_api_client = LogAPI(api_key=api_key)
    
    try:
        response = log_api_client.list(page_size=50)
        print(f"✓ Retrieved {len(response.results)} logs")
        
        for log in response.results:
            print(f"Log {log.unique_id}: {log.model} - {log.total_tokens} tokens - ${log.cost:.4f}")
            
        return response.results
    except Exception as e:
        print(f"✗ Error: {e}")
        return []

# Usage
list_logs_sync()

Asynchronous Example

import asyncio
import os
from dotenv import load_dotenv
from keywordsai.logs.api import LogAPI

load_dotenv()

async def list_logs_async():
    """Asynchronous log listing"""
    api_key = os.getenv("KEYWORDS_AI_API_KEY")
    log_api_client = LogAPI(api_key=api_key)
    
    try:
        response = await log_api_client.alist(
            page_size=50,
            sort_by="-id"
        )
        print(f"✓ Async retrieved {len(response.results)} logs")
        
        for log in response.results:
            print(f"Log {log.unique_id}: {log.model} - {log.total_tokens} tokens")
            
        return response.results
    except Exception as e:
        print(f"✗ Async error: {e}")
        return []

# Usage
asyncio.run(list_logs_async())

Sorting and Pagination

def list_logs_with_options():
    """List logs with sorting and pagination"""
    api_key = os.getenv("KEYWORDS_AI_API_KEY")
    log_api_client = LogAPI(api_key=api_key)
    
    # Sort by cost (highest first)
    expensive_logs = log_api_client.list(
        sort_by="-cost",
        page_size=25
    )
    print(f"Top 25 expensive logs: {len(expensive_logs.results)}")
    
    # Sort by latency (fastest first)
    fast_logs = log_api_client.list(
        sort_by="latency",
        page_size=25
    )
    print(f"Top 25 fastest logs: {len(fast_logs.results)}")
    
    # Get second page
    page_2_logs = log_api_client.list(
        page=2,
        page_size=100
    )
    print(f"Page 2 logs: {len(page_2_logs.results)}")

# Usage
list_logs_with_options()

Environment Filtering

def list_logs_by_environment():
    """List logs filtered by environment"""
    api_key = os.getenv("KEYWORDS_AI_API_KEY")
    log_api_client = LogAPI(api_key=api_key)
    
    # Get only production logs (default)
    prod_logs = log_api_client.list(
        is_test="false",
        page_size=50
    )
    print(f"Production logs: {len(prod_logs.results)}")
    
    # Get only test logs
    test_logs = log_api_client.list(
        is_test="true",
        page_size=50
    )
    print(f"Test logs: {len(test_logs.results)}")
    
    # Get logs from all environments
    all_env_logs = log_api_client.list(
        all_envs="true",
        page_size=50
    )
    print(f"All environment logs: {len(all_env_logs.results)}")

# Usage
list_logs_by_environment()

Convenience Functions

You can also use the convenience function to create a LogAPI client:

from keywordsai import create_log_client

client = create_log_client(api_key="your-api-key")
response = client.list(page_size=100)

Limitations

The SDK’s list() method only supports URL query parameters. For advanced filtering with operators (gt, lt, contains, etc.), you need to use the direct API endpoint with POST requests.

What’s NOT supported in the SDK:

• Complex filters in request body
• Metadata filtering
• Model filtering
• Date range filtering
• Custom field filtering

For advanced filtering, use the direct API:

import requests

url = "https://api.keywordsai.co/api/request-logs/"
headers = {"Authorization": f"Api-Key {api_key}"}
data = {
    "filters": {
        "model": {"operator": "", "value": ["gpt-4"]},
        "cost": {"operator": "gt", "value": [0.01]}
    }
}
response = requests.post(url, headers=headers, json=data)