> ## Documentation Index
> Fetch the complete documentation index at: https://www.edgee.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK - Send Method

> Complete guide to the send() method in the TypeScript SDK.

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:

| Property | Type | Description |
| - | - | - |
| `model` (The field is required.) | `string` | The model identifier to use (e.g., `"openai/gpt-5.2"`) |
| `input` | `string \| InputObject` | The 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:

```typescript theme={"dark"}
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:

| Property | Type | Description |
| - | - | - |
| `messages` (The field is required.) | `Message[]` | Array of conversation messages |
| `tools` | `Tool[]` | Array of function tools available to the model |
| `tool_choice` | `ToolChoice` | Controls which tool (if any) the model should call. See [Tools documentation](https://www.edgee.ai/docs/llm-router/sdk/typescript/tools.md) for details |
| `tags` | `string[]` | 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_model` | `string` | Compression 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:**

```typescript theme={"dark"}
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:**

```typescript theme={"dark"}
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:

| Property | Type | Description |
| - | - | - |
| `role` (The field is required.) | `string` | The role of the message sender: `"system"`, `"developer"`, `"user"`, `"assistant"`, or `"tool"` |
| `content` | `string` | The message content. Required for `system`, `user`, `tool` and `developer` roles. Optional for `assistant` when `tool_calls` is present |
| `name` | `string` | Optional name for the message sender |
| `tool_calls` | `ToolCall[]` | Array of tool calls made by the assistant. Only present in `assistant` messages |
| `tool_call_id` | `string` | ID 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:**

```typescript theme={"dark"}
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](https://www.edgee.ai/docs/llm-router/sdk/typescript/tools.md).

## Return Value

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

### SendResponse Object

| Property | Type | Description |
| - | - | - |
| `choices` | `Choice[]` | Array of completion choices (typically one) |
| `usage` | `Usage \| undefined` | Token usage information (if provided by the API) |
| `compression` | `Compression \| undefined` | Token compression metrics (if compression was applied) |

### Choice Object

Each choice in the `choices` array contains:

| Property | Type | Description |
| - | - | - |
| `index` | `number` | The index of this choice in the array |
| `message` | `Message` | The assistant's message response |
| `finish_reason` | `string \| null` | Reason why the generation stopped. Possible values: `"stop"`, `"length"`, `"tool_calls"`, `"content_filter"`, or `null` |

**Example - Handling Multiple Choices:**

```typescript theme={"dark"}
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:

| Property | Type | Description |
| - | - | - |
| `role` | `string` | The role of the message (typically `"assistant"`) |
| `content` | `string \| null` | The text content of the response. `null` when `tool_calls` is present |
| `tool_calls` | `ToolCall[] \| undefined` | Array of tool calls requested by the model (if any). See [Tools documentation](https://www.edgee.ai/docs/llm-router/sdk/typescript/tools.md) for details |

### Usage Object

Token usage information (when available):

| Property | Type | Description |
| - | - | - |
| `prompt_tokens` | `number` | Number of tokens in the prompt (after compression if applied) |
| `completion_tokens` | `number` | Number of tokens in the completion |
| `total_tokens` | `number` | Total tokens used (prompt + completion) |

**Example - Accessing Token Usage:**

```typescript theme={"dark"}
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):

| Property | Type | Description |
| - | - | - |
| `saved_tokens` | `number` | Number of tokens saved by compression |
| `cost_savings` | `number` | Estimated cost savings in micro-units (e.g. 27000 = \$0.027) |
| `reduction` | `number` | Percentage reduction (e.g. 18 = 18%, may be fractional) |
| `time_ms` | `number` | Time taken for compression in milliseconds |

**Example - Accessing Compression Metrics:**

```typescript theme={"dark"}
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`);
}
```

> [!NOTE]
>
> 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:

| Property | Type | Description |
| - | - | - |
| `text` | `string \| null` | Shortcut to `choices[0].message.content` |
| `message` | `Message \| null` | Shortcut to `choices[0].message` |
| `finishReason` | `string \| null` | Shortcut to `choices[0].finish_reason` |
| `toolCalls` | `ToolCall[] \| null` | Shortcut to `choices[0].message.tool_calls` |

**Example - Using Convenience Properties:**

```typescript theme={"dark"}
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:

```typescript theme={"dark"}
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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.