Skip to main content
POST
/
api
/
traces
/
list
/
{
  "filters": {
    "total_cost": {
      "operator": "gte",
      "value": [0.01]
    },
    "customer_identifier": {
      "operator": "",
      "value": ["user@example.com"]
    }
  }
}

{
  "count": 150,
  "next": "https://api.keywordsai.co/api/traces/list/?page=2",
  "previous": null,
  "results": [
    {
      "id": "trace_abc123",
      "trace_unique_id": "trace_abc123",
      "start_time": "2024-01-15T10:30:00Z",
      "end_time": "2024-01-15T10:30:02.5Z",
      "duration": 2.5,
      "span_count": 5,
      "llm_call_count": 2,
      "total_prompt_tokens": 150,
      "total_completion_tokens": 75,
      "total_tokens": 225,
      "total_cost": 0.00345,
      "error_count": 0,
      "input": {
        "messages": [{"role": "user", "content": "Explain quantum computing"}]
      },
      "output": {
        "choices": [
          {
            "message": {"role": "assistant", "content": "Quantum computing is..."}
          }
        ]
      },
      "metadata": {"user_id": "user123", "session_id": "session456"},
      "customer_identifier": "user@example.com",
      "environment": "production",
      "trace_group_identifier": "workflow_v1",
      "name": "chat_completion",
      "model": "gpt-4"
    }
  ]
}
Retrieves a paginated list of traces matching your filters. This endpoint supports both POST (recommended for complex filters) and GET for simple queries.

​
Authentication

All endpoints require API key authentication: 
Authorization: Bearer YOUR_API_KEY

​
Query Parameters

ParameterTypeDefaultDescription
start_timeISO 86011 hour agoStart of time range
end_timeISO 8601Current timeEnd of time range
pageinteger1Page number
page_sizeinteger50Results per page (max 1000)
sort_bystring-timestampSort field (prefix - for descending)
environmentstringAllFilter by environment

​
Supported Sort Fields

  • timestamp, start_time, end_time, duration
  • total_cost, total_tokens, total_prompt_tokens, total_completion_tokens
  • span_count, llm_call_count, error_count

​
Request Body (POST)

Use filters to refine results server-side. See the Filters API Reference for operators and format. 
{
  "filters": {
    "total_cost": {
      "operator": "gte",
      "value": [0.01]
    },
    "customer_identifier": {
      "operator": "",
      "value": ["user@example.com"]
    }
  }
}

​
Available Filter Fields

  • trace_unique_id, customer_identifier, environment
  • span_count, llm_call_count, error_count
  • total_cost, total_tokens, total_prompt_tokens, total_completion_tokens
  • duration, workflow_name (span_workflow_name)
  • Custom metadata via metadata__your_field

​
Examples

import requests

url = "https://api.keywordsai.co/api/traces/list/"
headers = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}
params = {
    "start_time": "2024-01-15T00:00:00Z",
    "end_time": "2024-01-15T23:59:59Z",
    "page_size": 20,
    "sort_by": "-total_cost"
}

body = {
    "filters": {
        "environment": {"operator": "", "value": ["production"]},
        "total_cost": {"operator": "gte", "value": [0.01]}
    }
}

response = requests.post(url, headers=headers, params=params, json=body)
print(response.json())

​
Response

{
  "count": 150,
  "next": "https://api.keywordsai.co/api/traces/list/?page=2",
  "previous": null,
  "results": [
    {
      "id": "trace_abc123",
      "trace_unique_id": "trace_abc123",
      "start_time": "2024-01-15T10:30:00Z",
      "end_time": "2024-01-15T10:30:02.5Z",
      "duration": 2.5,
      "span_count": 5,
      "llm_call_count": 2,
      "total_prompt_tokens": 150,
      "total_completion_tokens": 75,
      "total_tokens": 225,
      "total_cost": 0.00345,
      "error_count": 0,
      "input": {
        "messages": [{"role": "user", "content": "Explain quantum computing"}]
      },
      "output": {
        "choices": [
          {
            "message": {"role": "assistant", "content": "Quantum computing is..."}
          }
        ]
      },
      "metadata": {"user_id": "user123", "session_id": "session456"},
      "customer_identifier": "user@example.com",
      "environment": "production",
      "trace_group_identifier": "workflow_v1",
      "name": "chat_completion",
      "model": "gpt-4"
    }
  ]
}

​
Field Descriptions

FieldTypeDescription
trace_unique_idstringUnique trace identifier
start_timedatetimeWhen the trace started
end_timedatetimeWhen the trace ended
durationfloatTotal duration in seconds
span_countintegerTotal spans in the trace
llm_call_countintegerNumber of LLM calls
total_prompt_tokensintegerSum of input tokens
total_completion_tokensintegerSum of output tokens
total_tokensintegerTotal tokens used
total_costfloatTotal cost in USD
error_countintegerNumber of errors
inputobjectRoot span’s input (full object)
outputobjectRoot span’s output (full object)
metadataobjectCustom metadata
customer_identifierstringCustomer/user identifier
environmentstringEnvironment (e.g., production, test)
trace_group_identifierstringWorkflow group identifier
namestringRoot span name
modelstringPrimary model used

​
Error Responses

400 Bad Request
{ "detail": "Invalid parameters or filters" }
401 Unauthorized
{ "detail": "Your API key is invalid or expired, please check your API key at https://platform.keywordsai.co/platform/api/api-keys" }
500 Internal Server Error
{ "detail": "Server error" }