Chat Completions

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

Request Headers

Content-Type: application/json
Authorization: Bearer your-api-key

Request Body

array

required

Array of message objects representing the conversation history

Show Message Object

string

required

The role of the message sender. One of: system, user, assistant

string

required

The content of the message

string

Unique identifier for the simulated user. Optional if your agent doesn’t require user management.

string

Session identifier for conversation tracking. Optional if your agent doesn’t require session management.

object

Additional context about the simulation scenario

Show Metadata Fields

string

Identifier for the test scenario

string

User persona for the simulation

string

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"
  }
}

Response Format

array

required

Array containing the agent’s response

Show Choice Object

integer

Index of the choice (typically 0)

object

required

The agent’s response message

Show Message Object

string

Always “assistant” for agent responses

string

The agent’s response content

array

Array of tool calls made by the agent (if applicable)

string

Reason the response ended. Typically “stop”

string

Session identifier echoed from request

string

Unique identifier for this conversation

object

Agent performance metrics

Show Metadata Fields

number

Confidence score for the response (0-1)

integer

Time taken to generate response in milliseconds

array

List of tools/functions used in the response

object

Additional data for evaluation purposes

Show Evaluation Fields

boolean

Whether relevant data was found (context-specific)

string

Detected tone of the response

integer

Step in the resolution process

boolean

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
  }
}

Response with Tool Calls

{
  "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

Tool Calling

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

Performance Requirements

Response Time: Target < 5 seconds for standard requests
Throughput: Support 100 RPS for parallel simulations
Availability: 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.

Agent Integration Endpoints

Platform Endpoints

Overview

Endpoint

Request Headers

Request Body

Request Examples

Minimal Request

Full Request with Context

Response Format

Response Examples

Basic Response

Response with Tool Calls

Error Responses

400 Bad Request

429 Rate Limit

500 Internal Error

Implementation Notes

Tool Calling

Performance Requirements

Best Practices

​Overview

​Endpoint

​Request Headers

​Request Body

​Request Examples

​Minimal Request

​Full Request with Context

​Response Format

​Response Examples

​Basic Response

​Response with Tool Calls

​Error Responses

​400 Bad Request

​429 Rate Limit

​500 Internal Error

​Implementation Notes

​Tool Calling

​Performance Requirements

​Best Practices

Overview

Endpoint

Request Headers

Request Body

Request Examples

Minimal Request

Full Request with Context

Response Format

Response Examples

Basic Response

Response with Tool Calls

Error Responses

400 Bad Request

429 Rate Limit

500 Internal Error

Implementation Notes

Tool Calling

Performance Requirements

Best Practices