Overview The Chat Completions endpoint allows UserTrace to interact with your custom chat agents using the OpenAI Chat Completions format. This is the primary endpoint for text-based agent testing.
Endpoint POST /v1/chat/completions
Content-Type : application/json Authorization : Bearer your-api-key
Request Body Array of message objects representing the conversation history The role of the message sender. One of: system, user, assistant
The content of the message
Unique identifier for the simulated user. Optional if your agent doesn’t require user management.
Session identifier for conversation tracking. Optional if your agent doesn’t require session management.
Additional context about the simulation scenario Identifier for the test scenario
User persona for the simulation
Context about timing (e.g., “morning_rush”, “evening”)
Request Examples Minimal Request { "messages" : [ { "role" : "user" , "content" : "Hello, I need help" } ] }
Full Request with Context { "messages" : [ { "role" : "system" , "content" : "You are a helpful customer service agent." }, { "role" : "user" , "content" : "I need help with my order #12345" } ], "user_id" : "sim_user_abc123" , "session_id" : "session_xyz789" , "metadata" : { "scenario_id" : "financial_stress_delivery" , "persona" : "delivery_worker_bengaluru" , "time_of_day" : "morning_rush" , "stress_level" : "high" } }
Array containing the agent’s response Index of the choice (typically 0)
The agent’s response message Always “assistant” for agent responses
The agent’s response content
Array of tool calls made by the agent (if applicable)
Reason the response ended. Typically “stop”
Session identifier echoed from request
Unique identifier for this conversation
Agent performance metrics Confidence score for the response (0-1)
Time taken to generate response in milliseconds
List of tools/functions used in the response
Additional data for evaluation purposes Whether relevant data was found (context-specific)
Detected tone of the response
Step in the resolution process
Whether customer concern was acknowledged
Response Examples Basic Response { "choices" : [ { "index" : 0 , "message" : { "role" : "assistant" , "content" : "I'd be happy to help you with your order. Let me look up order #12345 for you." }, "finish_reason" : "stop" } ], "session_id" : "session_xyz789" , "chat_id" : "chat_456def" , "metadata" : { "agent_confidence" : 0.95 , "response_time_ms" : 1200 , "tools_used" : [ "order_lookup" ] }, "evaluation_metadata" : { "order_found" : true , "tone" : "empathetic" , "resolution_step" : 1 , "customer_acknowledged" : true } }
{ "choices" : [ { "index" : 0 , "message" : { "role" : "assistant" , "content" : "I found your order! Order #12345 is currently being prepared and will be shipped within 2 hours." , "tool_calls" : [ { "id" : "call_abc123" , "type" : "function" , "function" : { "name" : "get_order_status" , "arguments" : "{ \" order_id \" : \" 12345 \" }" , "result" : { "order_id" : "12345" , "status" : "preparing" , "estimated_ship_time" : "2 hours" , "tracking_number" : null } } } ] }, "finish_reason" : "stop" } ], "session_id" : "session_xyz789" , "chat_id" : "chat_456def" , "evaluation_metadata" : { "tool_called" : "get_order_status" , "tool_success" : true , "response_included_status" : true , "customer_informed" : true } }
Error Responses 400 Bad Request { "error" : { "message" : "Invalid request format: missing required field 'messages'" , "type" : "invalid_request_error" , "code" : "bad_request" } }
429 Rate Limit { "error" : { "message" : "Rate limit exceeded. Please wait before making another request." , "type" : "rate_limit_error" , "code" : "rate_limit_exceeded" } }
500 Internal Error { "error" : { "message" : "Internal server error. Please try again later." , "type" : "internal_error" , "code" : "server_error" } }
Implementation Notes If your agent uses function calling, you must handle all tool execution internally. The simulated user will send simple text requests, and your agent should:
Execute any necessary function calls
Include complete tool call information in the response
Provide the final answer incorporating tool results
Response Time : Target < 5 seconds for standard requestsThroughput : Support 100 RPS for parallel simulationsAvailability : 99.9% uptime during testing windows
Best Practices
Include relevant evaluation_metadata to help with scoring
Use consistent session_id for multi-turn conversations
Handle edge cases gracefully with appropriate error responses
Log requests and responses for debugging
Testing : Use tools like curl, Postman, or our SDK to test your endpoint before connecting to UserTrace.
