Skip to main content
The send() method is used to make non-streaming chat completion requests to the Edgee AI Gateway. It returns a Promise<SendResponse> with the model’s response.

​
Arguments

The send() method accepts a single SendOptions object with the following properties:
PropertyTypeDescription
model stringThe model identifier to use (e.g., "openai/gpt-5.2")
inputstring | InputObjectThe input for the completion. Can be a simple string or a structured InputObject

​
Input Types

​
String Input

When input is a string, it’s automatically converted to a user message: 
const response = await edgee.send({
  model: 'gpt-5.2',
  input: 'What is the capital of France?'
});

// Equivalent to: input: { messages: [{ role: 'user', content: 'What is the capital of France?' }] }
console.log(response.text);
// "The capital of France is Paris."

​
InputObject

When input is an InputObject, you have full control over the conversation:
PropertyTypeDescription
messages Message[]Array of conversation messages
toolsTool[]Array of function tools available to the model
tool_choiceToolChoiceControls which tool (if any) the model should call. See Tools documentation for details
tagsstring[]Optional tags to categorize and label the request for analytics and filtering. Can also be sent via the x-edgee-tags header (comma-separated)
compression_modelstringCompression model for this request: "claude", "codex", "opencode", "cursor". Each model is a bundle of compression strategies. Overrides API key settings when present.
Example with InputObject: 
const response = await edgee.send({
  model: 'gpt-5.2',
  input: {
    messages: [
      { role: 'user', content: 'What is 2+2?' }
    ]
  }
});

console.log(response.text);
// "2+2 equals 4."
Example with Tags: 
const response = await edgee.send({
  model: 'gpt-5.2',
  input: {
    messages: [
      { role: 'user', content: 'Summarize this article' }
    ],
    tags: ['summarization', 'production', 'user-123']
  }
});

​
Message Object

Each message in the messages array has the following structure:
PropertyTypeDescription
role stringThe role of the message sender: "system", "developer", "user", "assistant", or "tool"
contentstringThe message content. Required for system, user, tool and developer roles. Optional for assistant when tool_calls is present
namestringOptional name for the message sender
tool_callsToolCall[]Array of tool calls made by the assistant. Only present in assistant messages
tool_call_idstringID of the tool call this message is responding to. Required for tool role messages

​
Message Roles

  • system: System instructions that set the behavior of the assistant
  • developer: Instructions provided by the application developer, prioritized ahead of user messages.
  • user: Instructions provided by an end user.
  • assistant: Assistant responses (can include tool_calls)
  • tool: Results from tool/function calls (requires tool_call_id)
Example - System and User Messages: 
const response = await edgee.send({
  model: 'gpt-5.2',
  input: {
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'What is 2+2?' },
      { role: 'assistant', content: '2+2 equals 4.' },
      { role: 'user', content: 'What about 3+3?' }
    ]
  }
});

console.log(response.text);
// "3+3 equals 6."
For complete tool calling examples and best practices, see Tools documentation.

​
Return Value

The send() method returns a Promise<SendResponse> with the following structure:

​
SendResponse Object

PropertyTypeDescription
choicesChoice[]Array of completion choices (typically one)
usageUsage | undefinedToken usage information (if provided by the API)
compressionCompression | undefinedToken compression metrics (if compression was applied)

​
Choice Object

Each choice in the choices array contains:
PropertyTypeDescription
indexnumberThe index of this choice in the array
messageMessageThe assistant’s message response
finish_reasonstring | nullReason why the generation stopped. Possible values: "stop", "length", "tool_calls", "content_filter", or null
Example - Handling Multiple Choices: 
const response = await edgee.send({
  model: 'gpt-5.2',
  input: 'Give me a creative idea.'
});

// Process all choices
response.choices.forEach((choice, index) => {
  console.log(`Choice ${index}:`, choice.message.content);
  console.log(`Finish reason: ${choice.finish_reason}`);
});

​
Message Object (in Response)

The message in each choice has:
PropertyTypeDescription
rolestringThe role of the message (typically "assistant")
contentstring | nullThe text content of the response. null when tool_calls is present
tool_callsToolCall[] | undefinedArray of tool calls requested by the model (if any). See Tools documentation for details

​
Usage Object

Token usage information (when available):
PropertyTypeDescription
prompt_tokensnumberNumber of tokens in the prompt (after compression if applied)
completion_tokensnumberNumber of tokens in the completion
total_tokensnumberTotal tokens used (prompt + completion)
Example - Accessing Token Usage: 
const response = await edgee.send({
  model: 'gpt-5.2',
  input: 'Explain quantum computing briefly.'
});

if (response.usage) {
  console.log(`Prompt tokens: ${response.usage.prompt_tokens}`);
  console.log(`Completion tokens: ${response.usage.completion_tokens}`);
  console.log(`Total tokens: ${response.usage.total_tokens}`);
}

​
Compression Object

Token compression metrics (when compression is applied):
PropertyTypeDescription
saved_tokensnumberNumber of tokens saved by compression
cost_savingsnumberEstimated cost savings in micro-units (e.g. 27000 = $0.027)
reductionnumberPercentage reduction (e.g. 48 = 48%, may be fractional)
time_msnumberTime taken for compression in milliseconds
Example - Accessing Compression Metrics: 
const response = await edgee.send({
  model: 'gpt-5.2',
  input: {
    messages: [
      { role: 'user', content: 'Analyze this long document with lots of context...' }
    ],
    compression_model: "claude",
  }
});

if (response.compression) {
  console.log(`Saved tokens: ${response.compression.saved_tokens}`);
  console.log(`Reduction: ${response.compression.reduction}%`);
  console.log(`Cost savings: $${(response.compression.cost_savings / 1_000_000).toFixed(3)}`);
  console.log(`Time: ${response.compression.time_ms} ms`);
}
The compression object is only present when token compression is applied to the request. Simple queries may not trigger compression.

​
Convenience Properties

The SendResponse class provides convenience getters for easier access:
PropertyTypeDescription
textstring | nullShortcut to choices[0].message.content
messageMessage | nullShortcut to choices[0].message
finishReasonstring | nullShortcut to choices[0].finish_reason
toolCallsToolCall[] | nullShortcut to choices[0].message.tool_calls
Example - Using Convenience Properties: 
const response = await edgee.send({
  model: 'gpt-5.2',
  input: 'Hello!'
});

// Instead of: response.choices[0].message.content
console.log(response.text);

// Instead of: response.choices[0].message
console.log(response.message);

// Instead of: response.choices[0].finish_reason
console.log(response.finishReason);

// Instead of: response.choices[0].message.tool_calls
if (response.toolCalls) {
  console.log('Tool calls:', response.toolCalls);
}

​
Error Handling

The send() method can throw errors in several scenarios: 
try {
  const response = await edgee.send({
    model: 'gpt-5.2',
    input: 'Hello!'
  });
} catch (error) {
  if (error instanceof Error) {
    // API errors: "API error {status}: {message}"
    // Network errors: Standard fetch errors
    console.error('Request failed:', error.message);
  }
}

​
Common Errors

  • API errors: Error: API error {status}: {message} - The API returned an error status
  • Network errors: Standard fetch network errors
  • Invalid input: Errors from invalid request structure