List logs

The Logs List endpoint allows you to retrieve past logs with specified filters.

Both GET and POST methods are supported for listing logs. POST is recommended when using complex filters or when URL length limits might be exceeded. The same endpoint is also available at /api/request-logs/ (without /list/).

Response fields

Each log in the response includes:

Universal fields (All Span Types)

input (string): JSON-serialized representation of the span’s input data
output (string): JSON-serialized representation of the span’s output data
log_type (string): Type of span ("chat", "embedding", "workflow", etc.)

Legacy compatibility

For log_type="chat", "completion", "text", or "response":

prompt_messages (array): Full input messages array (extracted from input)
completion_message (object): Full output message object (extracted from output)

For other span types (embedding, workflow, etc.), type-specific fields are extracted based on the log_type. See log types for details.

Query parameters

You can add these parameters to the URL query string. For example:

"https://api.keywordsai.co/api/request-logs/list/?page=1&sort_by=-id&is_test=false&all_envs=false&fetch_filters=false&page_size=1"

start_time

string

required

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:00" // ISO 8601 format
}

end_time

string

required

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

Example

{
  "end_time": "2025-08-16T00:00:00" // ISO 8601 format
}

sort_by

string

required

The field to sort by. Default is -id (same as sort by -timestamp, but with better performance). - is for descending order, if not provided, it will be in ascending order.

Properties

string

Sort by the ID of each request.

cost

string

Sort by the cost of each request.

time_to_first_token

string

TTFT - useful for Voice AI applications

latency

string

Generation time of each request.

prompt_tokens

string

Input / prompt tokens of each request.

completion_tokens

string

Output / completion tokens of each request.

all_tokens

string

Total tokens of each request.

Example

{
  "sort_by": "cost" //sort by cost in ascending order.
}

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 the log is a test call or not. This parameter will override the all_envs parameter. Options: true, false.

fetch_filters

string

default:"false"

Whether to retrieve the available filtering options. Enabling this could slow down the response time. Options: true, false.

page_size

number

default:100

The number of logs to return per page. Maximum is 1000.

page

number

default:1

The page number of the current logs.

include_fields

string

Comma separated fields to be included in the response logs. This parameter allows you to specify which fields should be returned to improve performance and reduce response size.

include_fields guarantees the listed fields will be present in each log item, but it does not enforce exclusivity. The API may still return additional fields required for the endpoint (e.g., identifiers, pagination-related fields, or internal metadata).

Example

include_fields=custom_identifier,customer_identifier,id,latency

URL-based Filtering (Quick Filters)

You can filter logs directly via URL query parameters without constructing POST body filters. This is useful for sharing filtered views, bookmarking, or building dynamic filter links.

Basic Syntax

Simple filtering:

?<field>=<value>

Advanced filtering with operators:

?<field>[value]=<value>&<field>[operator]=<operator>&<field>[connector]=<connector>

Parameters

[value]: The filter value (required)
[operator]: Comparison operator (optional, defaults to "" for equality)
- "" (empty): Exact match (is)
- "not": Not equal (is not)
[connector]: Logic connector (optional, defaults to "AND")
- "AND": Combine with previous filter using AND
- "OR": Combine with previous filter using OR

Field Auto-Detection

The system automatically detects how to handle each URL parameter:

Pagination/Sort parameters: Skipped (page, page_size, sort_by, etc.)
Metadata fields starting with “metadata__”: Filter custom metadata
Known log fields: Filter directly on that field
Unknown fields: Treated as custom metadata (auto-prefix “metadata__“)

Known Log Fields

These fields can be filtered directly without the metadata__ prefix:

Identifiers: customer_identifier, custom_identifier, thread_identifier, prompt_id, unique_id
Tracing: trace_unique_id, span_name, span_workflow_name
Provider/Model: model, deployment_name, provider_id
Status: status_code, status, error_message
Config: environment, log_type, stream, temperature, max_tokens
Metrics: cost, latency, tokens_per_second, time_to_first_token, prompt_tokens, completion_tokens, total_request_tokens

URL Filter Examples

Filter by customer identifier

GET /api/request-logs/list/?customer_identifier=user_123

Filter with operator (status code not equal to 200)

GET /api/request-logs/list/?status_code[value]=200&status_code[operator]=not

Filter by custom metadata (auto-detected)

# This automatically becomes: metadata__event_id = "xxx"
GET /api/request-logs/list/?event_id=xxx

Explicit metadata filter

GET /api/request-logs/list/?metadata__user_type=premium

Multiple filters with OR logic

# (status_code = 200) OR (metadata__priority != "low")
GET /api/request-logs/list/?status_code[value]=200&status_code[connector]=OR&priority[value]=low&priority[operator]=not&priority[connector]=OR

Mixed known and unknown fields

# customer_identifier = "abc" AND metadata__event_id = "xxx" AND model = "gpt-4"
GET /api/request-logs/list/?customer_identifier=abc&event_id=xxx&model=gpt-4

Combining URL and POST Body Filters

URL filters and POST body filters can be combined. When there’s an overlap, URL filters take precedence.

Example: Combined filters

curl -X POST "https://api.keywordsai.co/api/request-logs/list/?customer_identifier=user_123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "status_code": {
        "operator": "",
        "value": [200]
      }
    }
  }'

This applies:

customer_identifier = "user_123" (from URL)
status_code = 200 (from POST body)

Limitations

URL filters support only equality ("") and not-equal ("not") operators
For complex operators (gt, gte, lt, lte, contains, etc.), use POST body filters
Each field can only have one value in URL (no arrays)
All URL values are treated as strings

Body parameters

You can add these parameters to the request body:

url = "https://api.keywordsai.co/api/request-logs/list/"
headers = {
    "Authorization": f"Bearer {YOUR_KEYWORDS_AI_API_KEY}",
}
data = {
    "filters":    {
      "cost": {
        "operator": "gt",
        "value": [0.01]
      },
    }
}
response = requests.post(url, headers=headers, json=data)

filters

object

The filters be applied to the logs. For available options in the response body, use the fetch_filters parameter.

If you want to filter your custom properties, you should add metadata__+ your custom property name. For example, if you want to filter your custom property my_custom_property, you should add metadata__my_custom_property to the filters.

Example

  {
    "name_of_metric": {
      "operator": "gt",
      "value": [100]
    },
  }

operator

string

required

Default is "" (equal).

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

Properties

string

Equal

Example

{
  "name_of_metric": {
    "operator": "", // equal
    "value": [100]
  },
}

iexact

string

case insensitive equal

string

Less than

lte

string

Less than or equal

string

Greater than

gte

string

Greater than or equal

contains

string

Contains

endswith

string

Ends with

startswith

string

Starts with

string

Can be used in arrays or text

isnull

string

Check if the field is null

icontains

string

Case insensitive contains

not

string

Not equal

url = "https://api.keywordsai.co/api/request-logs/list/?page=1&sort_by=-id&is_test=false&all_envs=false&fetch_filters=false&page_size=1"


from urllib.parse import urlencode
params = {
    "page": 1,
    "sort_by": "-id",
    "is_test": "false",
    "all_envs": "false",
    "fetch_filters": "false",
    "page_size": 1
}
url = f"https://api.keywordsai.co/api/request-logs/list/?{urlencode(params)}"
headers = {
    "Authorization": f"Bearer {YOUR_KEYWORDS_AI_API_KEY}",
}
data = {
    "filters": {}
}
response = requests.post(url, headers=headers, json=data)

{
    "count": 1250,
    "next": "https://api.keywordsai.co/api/request-logs/list/?page=2",
    "previous": null,
    "results": [
       {
        "unique_id": "xxxxx",
        "organization_key__name": "Keywords AI Default",
        "organization": "Keywords AI",
        "user": "[email protected]",
        "is_example": false,
        "status": "success",
        "log_type": "chat",
        
        // Universal fields (all span types)
        "input": "[{\"role\":\"system\",\"content\":\"You are a helpful assistant\"},{\"role\":\"user\",\"content\":\"What is Keywords AI?\"}]",
        "output": "{\"role\":\"assistant\",\"content\":\"Keywords AI is a unified DevOps platform for AI products.\"}",
        
        // Type-specific fields (extracted from input/output for chat types)
        "prompt_messages": [
                {
                    "role": "system",
                    "content": "You are a helpful assistant"
                },
                {
                    "role": "user",
                    "content": "What is Keywords AI?"
                }
        ],
        "completion_message": {
                "role": "assistant",
                "content": "Keywords AI is a unified DevOps platform for AI products."
        },
        
        // Telemetry
        "prompt_tokens": 452,
        "completion_tokens": 89,
        "cost": 0.0005869,
        "latency": 1.2114145755767822,
        "time_to_first_token": null,
        "tokens_per_second": 73.4,
        "routing_time": 0.0,
        
        // Model info
        "model": "gpt-3.5-turbo",
        "foundation_model": "gpt-3.5-turbo",
        "provider_id": "openai",
        
        // Function calling
        "tool_choice": null,
        "tools": null,
        "tool_calls": null,
        
        // Metadata
        "timestamp": "2024-06-24T21:33:06.601353Z",
        "metadata": {
            // any custom params you passed
        },
        "customer_identifier": "123456",
        "customer_email": "",
        "thread_identifier": null,
        "custom_identifier": null,
        "trace_unique_id": null,
        
        // Status
        "failed": false,
        "stream": false,
        "status_code": 200,
        "used_custom_credential": false
       }
    ]
}

Observe

Develop

Evaluate

Manage

Automation

Reference

Response fields

Universal fields (All Span Types)

Legacy compatibility

Query parameters

URL-based Filtering (Quick Filters)

Basic Syntax

Parameters

Field Auto-Detection

Known Log Fields

URL Filter Examples

Combining URL and POST Body Filters

Limitations

Body parameters

Observe

Develop

Evaluate

Manage

Automation

Reference

​Response fields

​Universal fields (All Span Types)

​Legacy compatibility

​Query parameters

​URL-based Filtering (Quick Filters)

​Basic Syntax

​Parameters

​Field Auto-Detection

​Known Log Fields

​URL Filter Examples

​Combining URL and POST Body Filters

​Limitations

​Body parameters

Response fields

Universal fields (All Span Types)

Legacy compatibility

Query parameters

URL-based Filtering (Quick Filters)

Basic Syntax

Parameters

Field Auto-Detection

Known Log Fields

URL Filter Examples

Combining URL and POST Body Filters

Limitations

Body parameters