StandardLoggingPayload Specification
Terminal success and failure callback events include kwargs["standard_logging_object"] when LiteLLM finishes building the standard payload. Custom logging callbacks should read request identity from kwargs["standard_logging_object"]["metadata"], rather than raw litellm_params metadata. Optional identity fields are null when unavailable. Intermediate streaming events and callbacks where payload construction fails can omit standard_logging_object.
StandardLoggingPayload
| Field | Type | Description |
|---|---|---|
id | str | Unique identifier |
trace_id | str | Trace multiple LLM calls belonging to same overall request |
session_id | str | End-user/conversation session id, from litellm_session_id. Independent of trace_id; only populated when litellm_settings.request_correlation_in_logs is enabled. Further docs |
call_type | str | Type of call |
response_cost | float | Cost of the response in USD ($) |
cost_breakdown | Optional[CostBreakdown] | Detailed cost breakdown object |
response_cost_failure_debug_info | StandardLoggingModelCostFailureDebugInformation | Debug information if cost tracking fails |
zero_cost_diagnostic | Optional[StandardLoggingZeroCostDiagnostic] | Why a billable request priced to $0. None when the cost is non-zero, the model is free or unmapped, or the request carried no usage. Further docs |
status | StandardLoggingPayloadStatus | Status of the payload |
status_fields | StandardLoggingPayloadStatusFields | Typed status fields for easy filtering and analytics |
total_tokens | int | Total number of tokens |
prompt_tokens | int | Number of prompt tokens |
completion_tokens | int | Number of completion tokens |
startTime | float | Start time of the call |
endTime | float | End time of the call |
completionStartTime | float | Time to first token for streaming requests |
response_time | float | Total response time. If streaming, this is the time to first token |
model_map_information | StandardLoggingModelInformation | Model mapping information |
model | str | Model name sent in request |
model_id | Optional[str] | Model ID of the deployment used |
model_group | Optional[str] | model_group used for the request |
api_base | str | LLM API base URL |
metadata | StandardLoggingMetadata | Metadata information |
cache_hit | Optional[bool] | Whether cache was hit |
cache_key | Optional[str] | Optional cache key |
saved_cache_cost | float | Cost saved by cache |
request_tags | list | List of request tags |
end_user | Optional[str] | Optional end user identifier |
requester_ip_address | Optional[str] | Optional requester IP address |
messages | Optional[Union[str, list, dict]] | Messages sent in the request |
response | Optional[Union[str, list, dict]] | LLM response |
error_str | Optional[str] | Optional error string |
error_information | Optional[StandardLoggingPayloadErrorInformation] | Optional error information |
model_parameters | dict | Model parameters |
hidden_params | StandardLoggingHiddenParams | Hidden parameters |
guardrail_information | Optional[list[StandardLoggingGuardrailInformation]] | One entry per guardrail that ran on the request |
Cost Breakdown
The cost_breakdown field provides detailed cost breakdown for completion requests as a CostBreakdown object containing:
input_cost: Cost of input/prompt tokens including cache creation tokensoutput_cost: Cost of output/completion tokens (including reasoning tokens if applicable)tool_usage_cost: Cost of built-in tools usage (e.g., web search, code interpreter)total_cost: Total cost of input + output + tool usagereasoning_cost: Cost of reasoning tokens, reported as a subset ofoutput_cost(populated when the model returns reasoning tokens, e.g.gemini-3.8-flash,o3)cache_read_cost: Cost of cache-read tokens, reported as a subset ofinput_cost(populated when cached tokens are present in the response)cache_creation_cost: Cost of cache-creation tokens, reported as a subset ofinput_cost(populated when prompt caching is used, e.g. Anthropic models)
Note: This field is populated for all call types. For non-completion calls, input_cost and output_cost may be 0.
The total cost relationship is: response_cost = cost_breakdown.total_cost
CostBreakdown Type
class CostBreakdown(TypedDict, total=False):
input_cost: float # Cost of input/prompt tokens in USD
output_cost: float # Cost of output/completion tokens in USD (includes reasoning)
tool_usage_cost: float # Cost of built-in tools usage in USD
total_cost: float # Total cost in USD
reasoning_cost: float # Cost of reasoning tokens in USD; subset of output_cost
cache_read_cost: float # Cost of cache-read tokens in USD; subset of input_cost
cache_creation_cost: float # Cost of cache-creation tokens in USD; subset of input_cost
StandardLoggingUserAPIKeyMetadata
These fields describe the virtual key that authenticated the request and the entities it belongs to. The proxy copies them from the key's auth object, so spend and budget values are the ones the proxy checked before this request ran and do not include its cost. A field is null when the key has no such entity or the entity has no value for it.
| Field | Type | Description |
|---|---|---|
user_api_key_hash | Optional[str] | Hash of the litellm virtual key |
user_api_key_alias | Optional[str] | Alias of the API key |
user_api_key_spend | Optional[float] | Spend of the key in USD |
user_api_key_max_budget | Optional[float] | Max budget of the key in USD |
user_api_key_budget_reset_at | Optional[str] | ISO 8601 time when the key's budget resets next |
user_api_key_user_spend | Optional[float] | Spend of the user who owns the key, in USD |
user_api_key_user_max_budget | Optional[float] | Max budget of the user who owns the key, in USD |
user_api_key_team_spend | Optional[float] | Spend of the key's team in USD |
user_api_key_team_max_budget | Optional[float] | Max budget of the key's team in USD |
user_api_key_org_id | Optional[str] | Organization ID associated with the key |
user_api_key_org_alias | Optional[str] | Organization alias associated with the key |
user_api_key_team_id | Optional[str] | Team ID associated with the key |
user_api_key_project_id | Optional[str] | Project ID associated with the key |
user_api_key_project_alias | Optional[str] | Project alias associated with the key |
user_api_key_user_id | Optional[str] | User ID associated with the key |
user_api_key_user_email | Optional[str] | Email of the user who owns the key, copied from that user's row. null when the key has no user_id or the user has no email. Callbacks already receive it on older releases such as v1.106.6, but SpendLogs (the /spend/logs API and the UI request log drawer) only stores it from v1.109.0 |
user_api_key_team_alias | Optional[str] | Team alias associated with the key |
user_api_key_end_user_id | Optional[str] | End-user ID associated with the key |
user_api_key_customer_member_id | Optional[str] | Customer member the request was charged to, when it runs under a customer hierarchy |
user_api_key_customer_team_id | Optional[str] | Customer team the request was charged to |
user_api_key_customer_org_id | Optional[str] | Customer organization the request was charged to |
user_api_key_customer_org_alias | Optional[str] | Alias of the customer organization. Can be absent when the request has no customer hierarchy |
user_api_key_customer_team_alias | Optional[str] | Alias of the customer team. Can be absent when the request has no customer hierarchy |
user_api_key_customer_member_alias | Optional[str] | Alias of the customer member. Can be absent when the request has no customer hierarchy |
user_api_key_customer_budget_scopes | Optional[str] | JSON string listing each customer level the request is charged to, with its key, entity_id and budget_limits. Can be absent when the request has no customer hierarchy |
user_api_key_customer_hierarchy | Optional[dict] | Full customer hierarchy the request ran under, including each level's spend and limits. Can be absent when the request has no customer hierarchy |
user_api_key_request_route | Optional[str] | Proxy route the request called, with path IDs replaced by placeholders, for example /v1/responses/{response_id} |
user_api_key_auth_metadata | Optional[dict] | The key's metadata, without the slots that hold callback credentials |
StandardLoggingMetadata
Inherits from StandardLoggingUserAPIKeyMetadata and adds:
| Field | Type | Description |
|---|---|---|
spend_logs_metadata | Optional[dict] | Key-value pairs for spend logging |
requester_ip_address | Optional[str] | Requester's IP address |
requester_metadata | Optional[dict] | Additional requester metadata |
vector_store_request_metadata | Optional[List[StandardLoggingVectorStoreRequest]] | Vector store request metadata |
requester_custom_headers | Dict[str, str] | Any custom (x-) headers sent by the client to the proxy. |
prompt_management_metadata | Optional[StandardLoggingPromptManagementMetadata] | Prompt management and versioning metadata |
mcp_tool_call_metadata | Optional[StandardLoggingMCPToolCall] | MCP (Model Context Protocol) tool call information and cost tracking |
applied_guardrails | Optional[List[str]] | List of applied guardrail names |
usage_object | Optional[dict] | Raw usage object from the LLM provider |
cold_storage_object_key | Optional[str] | S3/GCS object key for cold storage retrieval |
StandardLoggingVectorStoreRequest
| Field | Type | Description |
|---|---|---|
| vector_store_id | Optional[str] | ID of the vector store |
| custom_llm_provider | Optional[str] | Custom LLM provider the vector store is associated with (e.g., bedrock, openai, anthropic) |
| query | Optional[str] | Query to the vector store |
| vector_store_search_response | Optional[VectorStoreSearchResponse] | OpenAI format vector store search response |
| start_time | Optional[float] | Start time of the vector store request |
| end_time | Optional[float] | End time of the vector store request |
StandardLoggingAdditionalHeaders
| Field | Type | Description |
|---|---|---|
x_ratelimit_limit_requests | int | Rate limit for requests |
x_ratelimit_limit_tokens | int | Rate limit for tokens |
x_ratelimit_remaining_requests | int | Remaining requests in rate limit |
x_ratelimit_remaining_tokens | int | Remaining tokens in rate limit |
StandardLoggingHiddenParams
| Field | Type | Description |
|---|---|---|
model_id | Optional[str] | Optional model ID |
cache_key | Optional[str] | Optional cache key |
api_base | Optional[str] | Optional API base URL |
response_cost | Optional[str] | Optional response cost |
additional_headers | Optional[StandardLoggingAdditionalHeaders] | Additional headers |
batch_models | Optional[List[str]] | Only set for Batches API. Lists the models used for cost calculation |
litellm_model_name | Optional[str] | Model name sent in request |
StandardLoggingModelInformation
| Field | Type | Description |
|---|---|---|
model_map_key | str | Model map key |
model_map_value | Optional[ModelInfo] | Optional model information |
StandardLoggingModelCostFailureDebugInformation
| Field | Type | Description |
|---|---|---|
error_str | str | Error string |
traceback_str | str | Traceback string |
model | str | Model name |
cache_hit | Optional[bool] | Whether cache was hit |
custom_llm_provider | Optional[str] | Optional custom LLM provider |
base_model | Optional[str] | Optional base model |
call_type | str | Call type |
custom_pricing | Optional[bool] | Whether custom pricing was used |
StandardLoggingZeroCostDiagnostic
| Field | Type | Description |
|---|---|---|
reason | Literal["missing_pricing_key", "pricing_not_applied", "cost_calculation_error"] | Why the request priced to $0, the same value as the reason label on litellm_zero_cost_requests_total |
pricing_model | str | The pricing entry the request was judged against, a deployment id or a model cost map key |
missing_pricing_keys | Tuple[str, ...] | The rate keys the usage needed that the entry does not declare, empty unless reason is missing_pricing_key |
StandardLoggingPayloadErrorInformation
| Field | Type | Description |
|---|---|---|
error_code | Optional[str] | Optional error code (eg. "429") |
error_class | Optional[str] | Optional error class (eg. "RateLimitError") |
llm_provider | Optional[str] | LLM provider that returned the error (eg. "openai")` |
error_cooldown_deployments | Optional[Tuple[CooldownDeploymentInfo, ...]] | Set when the router refused the request because every deployment it could route to was in cooldown. Each entry has the deployment's model_id and configured api_base, with any key= value masked. Deployments the request's team, tags or allowed region rule out are left out. None for every other error |
StandardLoggingPayloadStatus
A literal type with two possible values:
"success""failure"
StandardLoggingGuardrailInformation
| Field | Type | Description |
|---|---|---|
guardrail_name | Optional[str] | Guardrail name |
guardrail_provider | Optional[str] | Guardrail provider |
guardrail_mode | Optional[Union[GuardrailEventHooks, List[GuardrailEventHooks]]] | Guardrail mode |
guardrail_request | Optional[dict] | Guardrail request |
guardrail_response | Optional[Union[dict, str, List[dict]]] | Guardrail response |
guardrail_status | GuardrailStatus | Guardrail execution status, one of the GuardrailStatus values |
start_time | Optional[float] | Start time of the guardrail |
end_time | Optional[float] | End time of the guardrail |
duration | Optional[float] | Duration of the guardrail in seconds |
masked_entity_count | Optional[Dict[str, int]] | Count of masked entities |
StandardLoggingPayloadStatusFields
Typed status fields for easy filtering and analytics.
| Field | Type | Description |
|---|---|---|
llm_api_status | StandardLoggingPayloadStatus | Status of the LLM API call: "success" if completed successfully, "failure" if errored |
guardrail_status | GuardrailStatus | Status of guardrail execution (see below) |
StandardLoggingPayloadStatus
A literal type with two possible values:
"success"- The LLM API request completed successfully"failure"- The LLM API request failed
GuardrailStatus
A literal type with five possible values:
"success"- Guardrail ran and allowed content through (no violations detected)"guardrail_flagged"- Guardrail allowed content through but recorded a non-blocking violation"guardrail_intervened"- Guardrail blocked or modified content due to policy violations"guardrail_failed_to_respond"- Guardrail had a technical failure or API error"not_run"- No guardrail was executed for this request
Usage Examples
Filter logs for requests where guardrails intervened:
{
"status_fields": {
"guardrail_status": "guardrail_intervened"
}
}
Find guardrail technical failures:
{
"status_fields": {
"guardrail_status": "guardrail_failed_to_respond"
}
}
Get successful LLM requests:
{
"status_fields": {
"llm_api_status": "success"
}
}
Find requests where guardrails ran successfully without intervention:
{
"status_fields": {
"guardrail_status": "success",
"llm_api_status": "success"
}
}
Find requests where no guardrail was run:
{
"status_fields": {
"guardrail_status": "not_run"
}
}
StandardLoggingPromptManagementMetadata
Used for tracking prompt versioning and management information.
| Field | Type | Description |
|---|---|---|
prompt_id | str | Required. Unique identifier for the prompt template or version |
prompt_variables | Optional[dict] | Variables/parameters used in the prompt template (e.g., {"user_name": "John", "context": "support"}) |
prompt_integration | str | Required. Integration or system managing the prompt (e.g., "langfuse", "promptlayer", "custom") |
StandardLoggingMCPToolCall
Used to track Model Context Protocol (MCP) tool calls within LiteLLM requests. This provides detailed logging for external tool integrations.
| Field | Type | Description |
|---|---|---|
name | str | Required. The name of the tool being called (e.g., "get_weather", "search_database") |
arguments | dict | Required. Arguments passed to the tool as key-value pairs |
result | Optional[dict] | The response/result returned by the tool execution (populated by custom logging hooks) |
mcp_server_name | Optional[str] | Name of the MCP server that handled the tool call (e.g., "weather-service", "database-connector") |
mcp_server_logo_url | Optional[str] | URL for the MCP server's logo (used for UI display in LiteLLM dashboard) |
namespaced_tool_name | Optional[str] | Fully qualified tool name including server prefix (e.g., "deepwiki-mcp/get_page_content", "github-mcp/create_issue") |
mcp_server_cost_info | Optional[MCPServerCostInfo] | Cost tracking information for the tool call |
MCPServerCostInfo
Cost tracking structure for MCP server tool calls:
| Field | Type | Description |
|---|---|---|
default_cost_per_query | Optional[float] | Default cost in USD for any tool call to this MCP server |
tool_name_to_cost_per_query | Optional[Dict[str, float]] | Per-tool cost mapping for granular pricing (e.g., {"search": 0.01, "create": 0.05}) |
Usage
# Basic MCP tool call metadata
mcp_tool_call = {
"name": "search_documents",
"arguments": {
"query": "machine learning tutorials",
"limit": 10,
"filter": "type:pdf"
},
"mcp_server_name": "document-search-service",
"namespaced_tool_name": "docs-mcp/search_documents",
"mcp_server_cost_info": {
"default_cost_per_query": 0.02,
"tool_name_to_cost_per_query": {
"search_documents": 0.02,
"get_document": 0.01
}
}
}
# optional result field (via custom logging hooks)
mcp_tool_call_with_result = {
"name": "search_documents",
"arguments": {
"query": "machine learning tutorials",
"limit": 10,
"filter": "type:pdf"
},
"result": {
"documents": [...],
"total_found": 42,
"search_time_ms": 150
},
"mcp_server_name": "document-search-service",
"namespaced_tool_name": "docs-mcp/search_documents",
"mcp_server_cost_info": {
"default_cost_per_query": 0.02,
"tool_name_to_cost_per_query": {
"search_documents": 0.02,
"get_document": 0.01
}
}
}