Skip to main content
Some intro here if necessary with context and feature links
Any notes

​
Query parameters

​
start_time
string
Start time in ISO 8601 format. Defaults to 1 hour ago.
"start_time": "2025-01-01T00:00:00Z"
​
page
integer
default:1
Page number for pagination.
​
page_size
integer
default:100
Number of items per page. Maximum is 1000.
​
sort_by
string
default:"-id"
Field to sort by. Prefix with - for descending order.
  • id / -id: Sort by ID
  • cost / -cost: Sort by cost
  • latency / -latency: Sort by latency
  • timestamp / -timestamp: Sort by timestamp

​
Path parameters

​
unique_id
string
required
The unique identifier of the resource to retrieve.

​
Request body

​
Core fields

​
input
string | object | array
Universal input field for the span. Structure depends on log_type:
  • Chat: JSON string of messages array or messages array directly
  • Embedding: Text string or array of strings
  • Workflow/Task: Any JSON-serializable structure
"input": "[{\"role\":\"user\",\"content\":\"Hello\"}]"

"input": "Keywords AI is an LLM observability platform"
​
output
string | object | array
Universal output field for the span. Structure depends on log_type.
"output": "{\"role\":\"assistant\",\"content\":\"Hi! How can I help?\"}"
​
log_type
string
default:"chat"
Type of span being logged. Determines how input and output are parsed.Supported types:
  • "chat" - Chat completion requests (default)
  • "embedding" - Embedding generation
  • "workflow" or "agent" - Workflow execution
  • "task" or "tool" - Task execution
  • "function" - Function call
  • "custom" - Custom span type
If not specified, defaults to "chat". For complete specifications of each type, see log types.
​
model
string
The model used for the inference. Optional but recommended for chat/completion/embedding types.
"model": "gpt-4o-mini"

​
Telemetry

​
usage
object
Token usage information for the request.
​
prompt_tokens
integer
Number of tokens in the prompt/input.
​
completion_tokens
integer
Number of tokens in the completion/output.
​
total_tokens
integer
Total tokens (prompt + completion).
{
  "usage": {
    "prompt_tokens": 150,
    "completion_tokens": 85,
    "total_tokens": 235
  }
}
​
cost
float
Cost of the inference in US dollars. If not provided, will be calculated automatically based on model pricing.
​
latency
float
Total request latency in seconds.
Previously called generation_time. Both field names are supported for backward compatibility.
​
time_to_first_token
float
Time to first token (TTFT) in seconds. Useful for streaming responses and voice AI applications.

​
Metadata

​
metadata
object
Custom metadata properties for analytics and filtering.
{
  "metadata": {
    "environment": "production",
    "version": "v1.0.0",
    "user_tier": "premium"
  }
}
​
customer_identifier
string
An identifier for the customer that invoked this request. Helps with visualizing user activities.
"customer_identifier": "user_123"
​
thread_identifier
string
A unique identifier for the conversation thread. Useful for multi-turn conversations.
​
custom_identifier
string
Same functionality as metadata, but indexed for faster querying.
"custom_identifier": "ticket_12345"

​
Workflow & tracing

​
trace_unique_id
string
Unique identifier for the trace. Used to link multiple spans together in distributed tracing.
​
span_workflow_name
string
Name of the workflow this span belongs to.
​
span_name
string
Name of this specific span/task within the workflow.

​
Body parameters

​
filters
object
The filters to be applied to the logs.
If you want to filter your custom properties, add metadata__ prefix. For example, to filter my_custom_property, use metadata__my_custom_property.
{
  "filters": {
    "cost": {
      "operator": "gt",
      "value": [0.01]
    },
    "metadata__user_tier": {
      "operator": "in",
      "value": ["premium", "enterprise"]
    }
  }
}
​
operator
string
Comparison operator for filtering. Default is "" (equal).
  • "" (empty string): Equal
  • "lt": Less than
  • "lte": Less than or equal
  • "gt": Greater than
  • "gte": Greater than or equal
  • "contains": Contains substring
  • "icontains": Case-insensitive contains
  • "startswith": Starts with
  • "endswith": Ends with
  • "in": Value in array
  • "not": Not equal
  • "isnull": Check if field is null

​
Advanced parameters

​
Tool calls and function calling

​
tools
array
A list of tools the model may call. Currently, only functions are supported as a tool.
​
type
string
required
The type of the tool. Currently, only function is supported.
​
function
object
required
Function definition containing name, description, and parameters.
"tools": [
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get current weather",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {"type": "string"}
        },
        "required": ["location"]
      }
    }
  }
]
​
tool_choice
string | object
Controls which (if any) tool is called by the model. Can be "none", "auto", or an object specifying a specific tool.
"tool_choice": {
  "type": "function",
  "function": {"name": "get_weather"}
}

​
Error handling and status

​
status_code
integer
default:200
The HTTP status code for the request. Default is 200 (success).
All valid HTTP status codes are supported: 200, 201, 400, 401, 403, 404, 429, 500, 502, 503, 504, etc.
​
error_message
string
Error message if the request failed. Default is empty string.
​
warnings
string | object
Any warnings that occurred during the request.

​
API controls

​
keywordsai_api_controls
object
Control the behavior of the Keywords AI logging API.
​
block
boolean
default:true
If false, the server immediately returns initialization status without waiting for log completion.
{
  "keywordsai_api_controls": {
    "block": true
  }
}

​
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, type-specific fields are extracted based on the log_type. See log types for details.

​
Identifiers

  • id (string): Unique identifier for the log
  • organization_id (string): Organization’s unique ID
  • customer_identifier (string): Customer identifier
  • thread_identifier (string): Thread identifier

​
Telemetry

  • cost (float): Cost in USD
  • latency (float): Request latency in seconds
  • prompt_tokens (integer): Input tokens
  • completion_tokens (integer): Output tokens
  • total_request_tokens (integer): Total tokens
  • time_to_first_token (float): TTFT in seconds
  • tokens_per_second (float): Generation speed

​
Status

  • status (string): Request status ("success", "error")
  • status_code (integer): HTTP status code
  • error_message (string): Error message if failed

​
Response

Returns the created log object with generated fields. 
{
  "id": "log_abc123",
  "status": "success",
  "cost": 0.000123,
  "timestamp": "2025-01-01T10:30:00Z",
  "organization_id": "org_xyz789",
  "customer_identifier": "user_123"
}

import requests

url = "https://api.keywordsai.co/api/request-logs/create/"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "log_type": "chat",
    "model": "gpt-4o-mini",
    "input": '[{"role":"user","content":"Hello"}]',
    "output": '{"role":"assistant","content":"Hi! How can I help?"}',
    "usage": {
        "prompt_tokens": 10,
        "completion_tokens": 8,
        "total_tokens": 18
    },
    "customer_identifier": "user_123",
    "latency": 1.2,
    "metadata": {
        "environment": "production"
    }
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

{
  "id": "log_abc123",
  "unique_id": "log_abc123",
  "organization_id": "org_xyz789",
  "customer_identifier": "user_123",
  "status": "success",
  "cost": 0.000123,
  "timestamp": "2025-01-01T10:30:00Z"
}