# Multi Order

## Get Multi Order

<mark style="color:blue;">GET</mark> `/api/multi_order/{id}`

Get detailed information about a specific multi-order including its child orders, execution status, and key parameters. This endpoint provides comprehensive information about the multi-order structure and its current state.

**Path Parameters**

| Name | Type   | Description                        |
| ---- | ------ | ---------------------------------- |
| `id` | string | UUID of multi order. **Required.** |

**Query Parameters**

| Name                   | Type    |                                                                    |
| ---------------------- | ------- | ------------------------------------------------------------------ |
| `include_child_orders` | boolean | Include full child order details in the response (default: false). |

**Example Request**

```
GET /api/multi_order/6debb950-614a-4366-b73b-7d7574fd9e15?include_child_orders=true
Authorization: Bearer <token>
```

**Response Codes**

{% tabs %}
{% tab title="200: OK" %}

```json
{
    "id": "397e42c1-a617-458b-9db9-dc51f326b918",
    "created_at": "2025-01-13T20:33:22.331268Z",
    "updated_at": "2025-01-13T20:33:22.331288Z",
    "start_datetime": "2025-01-13T20:33:22.323949Z",
    "duration": 600,
    "exposure_tolerance": "0.50000000000000000000",
    "notional_exposure": 34.554926518,
    "executed_notional": 93712.607473482,
    "is_active": false,
    "child_order_ids": [
        "5ee11fdd-334d-418a-b138-7df74f17e417",
        "54509111-7204-4626-8513-d7f040f76bf3"
    ],
    "strategy": "ccb82677-249d-4b01-8f60-7a02379e963a",
    "strategy_params": {},
    "engine_passiveness": "0.02000000000000000000",
    "schedule_discretion": "0.06000000000000000000",
    "alpha_tilt": "0.00000000000000000000",
    "pov_limit": null,
    "limit_price_spread": null,
    "order_condition": "ETH-USDT@Binance ETH:PERP-USDT@Binance - 1 >",
    "order_condition_vars": {},
    "order_condition_expiry": null,
    "user": "13",
    "status": "SCHEDULED",
    "failure_reason": "",
    "completely_filled": true,
    "is_paused": false,
    "pct_filled": 100.0,
    "account_names": [
        "mock"
    ],
    "pairs": "BTC-USDT,BTC:PERP-USDT",
    "calculated_status": "COMPLETE",
    "sell_token_amount": "0.50000000000000000000, 46871.66540000000000000000",
    "buy_token": "USDT, BTC:PERP",
    "sell_token": "BTC, USDT"
}
```

{% endtab %}

{% tab title="400: Bad Request" %}

```json
{
    "error": "unable to get multi order"
}
```

{% endtab %}

{% tab title="404: Notfound" %}

```
{
    "error": "multi order not found"
}
```

{% endtab %}
{% endtabs %}

## Get Multi Orders

<mark style="color:blue;">GET</mark> `/api/multi_orders/`

Paginated multi orders fetched given the filter options

**Query Parameters**

| Name                   | Type    |                                                                                                                                         |
| ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `include_child_orders` | boolean | Include full child order details in the response (default: false).                                                                      |
| `custom_order_ids`     | string  | comma separated list of values                                                                                                          |
| `statuses`             | string  | comma separated list of order statuses[Type Reference](/interacting-with-the-api/api-reference/type-reference.md#multiorderstatus-enum) |
| `before`               | string  | iso format datetime ex. 2025-08-11T12:00:00                                                                                             |
| `after`                | string  | iso format datetime ex. 2025-08-11T12:00:00                                                                                             |
| `page_number`          | integer | default: 1                                                                                                                              |
| `page_size`            | integer | default: 100                                                                                                                            |

**Example Request**

```
GET /api/multi_order/6debb950-614a-4366-b73b-7d7574fd9e15?include_child_orders=true
Authorization: Bearer <token>
```

**Response Codes**

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "multi_orders": [
    {
      "id": "6debb950-614a-4366-b73b-7d7574fd9e15",
      "created_at": "2023-12-01T10:00:00Z",
      "updated_at": "2023-12-01T10:30:00Z",
      "start_timedate": "2023-12-01T10:00:00Z",
      "duration": 3600,
      "exposure_tolerance": "0.05",
      "notional_exposure": "22500.00",
      "executed_notional": "22500.00",
      "child_order_ids": [
        "7fecb951-725b-5477-c84c-8e8685ge0f26",
        "8gfdca62-836c-6588-d95d-9f9796hf1g37"
      ],
      "accounts": ["binance_main", "coinbase_pro"],
      "strategy": "TWAP",
      "strategy_params": {
        "interval": 300,
        "slices": 12
      },
      "engine_passiveness": "0.5",
      "schedule_discretion": "0.3",
      "alpha_tilt": "0.1",
      "limit_price_spread": null,
      "failure_reason": null,
      "pct_filled": "100.00",
      "account_names": ["binance_main", "coinbase_pro"],
      "pairs": "BTC-USD,ETH-USD",
      "status": "COMPLETED",
      "is_active": false,
      "is_paused": false,
      "fee_notional": "22.50",
      "order_condition": "",
      "custom_order_id": "multi_order_123",
      "child_orders": [
        {
          "id": "7fecb951-725b-5477-c84c-8e8685ge0f26",
          "custom_order_id": "child_order_1",
          "parent_order_id": "6debb950-614a-4366-b73b-7d7574fd9e15",
          "notes": "",
          "pair": "BTC-USD",
          "side": "buy",
          "exchanges": ["binance"],
          "buy_token": "BTC",
          "buy_token_amount": "0.25",
          "sell_token": "USD",
          "sell_token_amount": "11250.00",
          "strategy": "TWAP",
          "strategy_params": {
            "interval": 300,
            "slices": 6
          },
          "status": "COMPLETED",
          "executed_notional": "11250.00",
          "pct_filled": "100.00",
          "created_at": "2023-12-01T10:00:00Z",
          "updated_at": "2023-12-01T10:30:00Z",
          "time_start": "2023-12-01T10:00:00Z",
          "duration": 1800,
          "limit_price": "45000.00",
          "engine_passiveness": "0.5",
          "schedule_discretion": "0.3",
          "alpha_tilt": "0.1",
          "is_active": false,
          "is_paused": false,
          "failure_reason": null,
          "fee": "11.25",
          "fills": [
            {
              "id": "fill_001",
              "timestamp": "2023-12-01T10:05:00Z",
              "quantity": "0.04166667",
              "price": "45000.00",
              "notional": "1875.00",
              "venue": "binance",
              "fee": "1.875"
            }
          ]
        }
      ]
    }
  ],
  "page_number": 1,
  "page_size": 100,
  "num_pages": 2,
  "multi_order_count": 144
}
```

{% endtab %}

{% tab title="400: Bad Request" %}

```json
{
    "errors": ["<field_name> is invalid"]
}
```

{% endtab %}
{% endtabs %}

## Submit Multi Order

<mark style="color:green;">`POST`</mark> `/api/multi_orders/`&#x20;

Submit a multi-order containing multiple child orders for scheduling and execution. This endpoint allows you to create a group of related orders that share common parameters while allowing individual customization for each child order.

**Request Body**

<table><thead><tr><th>Name</th><th>Type</th><th>Required<select><option value="BwDrg5Fsd3xb" label="Yes" color="blue"></option><option value="qafzwkzoVOe9" label="No" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><code>accounts</code></td><td>array[string]</td><td><span data-option="BwDrg5Fsd3xb">Yes</span></td><td>List of account names to use for the multi-order</td></tr><tr><td><code>duration</code></td><td>integer</td><td><span data-option="BwDrg5Fsd3xb">Yes</span></td><td>Duration of the multi-order in seconds</td></tr><tr><td><code>strategy</code></td><td>string</td><td><span data-option="BwDrg5Fsd3xb">Yes</span></td><td>Strategy name to use for execution.  Ex. VWAP</td></tr><tr><td><code>engine_passiveness</code></td><td>decimal</td><td><span data-option="BwDrg5Fsd3xb">Yes</span></td><td>Engine passiveness value (0.0 to 1.0)</td></tr><tr><td><code>schedule_discretion</code></td><td>decimal</td><td><span data-option="BwDrg5Fsd3xb">Yes</span></td><td>Schedule discretion value (0.0 to 1.0)</td></tr><tr><td><code>child_orders</code></td><td>array[object]</td><td><span data-option="BwDrg5Fsd3xb">Yes</span></td><td>Array of child order objects</td></tr><tr><td><code>strategy_params</code></td><td>object</td><td><span data-option="qafzwkzoVOe9">No</span></td><td>Strategy-specific parameters</td></tr><tr><td><code>alpha_tilt</code></td><td>decimal</td><td><span data-option="qafzwkzoVOe9">No</span></td><td>Alpha tilt value for order execution</td></tr><tr><td><code>exposure_tolerance</code></td><td>decimal</td><td><span data-option="qafzwkzoVOe9">No</span></td><td>Exposure tolerance for the multi-order</td></tr><tr><td><code>limit_price_spread</code></td><td>decimal</td><td><span data-option="qafzwkzoVOe9">No</span></td><td>Dynamic limit price spread for spread trades</td></tr><tr><td><code>order_condition</code></td><td>string</td><td><span data-option="qafzwkzoVOe9">No</span></td><td>Conditional order expression</td></tr><tr><td><code>start_timedate</code></td><td>string</td><td><span data-option="qafzwkzoVOe9">No</span></td><td>ISO 8601 timestamp for order start (defaults to now)</td></tr><tr><td><code>custom_order_id</code></td><td>string</td><td><span data-option="qafzwkzoVOe9">No</span></td><td>Custom identifier for the multi-order</td></tr><tr><td><code>notes</code></td><td>string</td><td><span data-option="qafzwkzoVOe9">No</span></td><td>Additional notes for the multi-order</td></tr></tbody></table>

### Child Order Object

<table><thead><tr><th>Name</th><th>Type</th><th>Required<select><option value="wsO8iQjmz9aI" label="Yes" color="blue"></option><option value="K3QTZ5iCzExW" label="No" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><code>pair</code></td><td>string</td><td><span data-option="wsO8iQjmz9aI">Yes</span></td><td>Trading pair symbol</td></tr><tr><td><code>side</code></td><td>string</td><td><span data-option="wsO8iQjmz9aI">Yes</span></td><td>Order side: buy or sell</td></tr><tr><td><code>base_asset_qty</code></td><td>decimal</td><td><span data-option="wsO8iQjmz9aI">Yes</span></td><td>Base asset quantity</td></tr><tr><td><code>accounts</code></td><td>array[string]</td><td><span data-option="K3QTZ5iCzExW">No</span></td><td>Specific accounts for this child order (overrides parent accounts)</td></tr><tr><td><code>quote_asset_qty</code></td><td>decimal</td><td><span data-option="K3QTZ5iCzExW">No</span></td><td>Quote asset quantity (alternative to <code>base_asset_qty</code>)</td></tr><tr><td><code>notes</code></td><td>string</td><td><span data-option="K3QTZ5iCzExW">No</span></td><td>Notes specific to this child order</td></tr><tr><td><code>alpha_tilt</code></td><td>decimal</td><td><span data-option="K3QTZ5iCzExW">No</span></td><td>Alpha tilt specific to this child order</td></tr><tr><td><code>pos_side</code></td><td>string</td><td><span data-option="K3QTZ5iCzExW">No</span></td><td>Position side: long or short.  Required if exchange account is configured to be in Hedge Mode.</td></tr></tbody></table>

#### Example Request

```
POST /api/multi_orders/
Authorization: Bearer <token>
Content-Type: application/json

{
  "accounts": ["binance_main"],
  "duration": 3600,
  "strategy": "TWAP",
  "engine_passiveness": 0.5,
  "schedule_discretion": 0.3,
  "alpha_tilt": 0.1,
  "exposure_tolerance": 0.05,
  "custom_order_id": "multi_order_123",
  "notes": "for xyz",
  "child_orders": [
    {
      "pair": "BTC:PERP-USDT",
      "side": "buy",
      "quote_asset_qty": 100000,
    },
    {
      "pair": "ETH:PERP-USDT",
      "side": "sell",
      "quote_asset_qty": 100000,
    }
  ]
}
```

**Response**

{% tabs %}
{% tab title="201: Created" %}

```json
{
    "id": "397e42c1-a617-458b-9db9-dc51f326b918",
    "created_at": "2025-01-13T20:33:22.331268Z",
    "updated_at": "2025-01-13T20:33:22.331288Z",
    "start_datetime": "2025-01-13T20:33:22.323949Z",
    "duration": 600,
    "exposure_tolerance": "0.50000000000000000000",
    "notional_exposure": 34.554926518,
    "executed_notional": 93712.607473482,
    "is_active": false,
    "child_order_ids": [
        "5ee11fdd-334d-418a-b138-7df74f17e417",
        "54509111-7204-4626-8513-d7f040f76bf3"
    ],
    "strategy": "ccb82677-249d-4b01-8f60-7a02379e963a",
    "strategy_params": {},
    "engine_passiveness": "0.02000000000000000000",
    "schedule_discretion": "0.06000000000000000000",
    "alpha_tilt": "0.00000000000000000000",
    "pov_limit": null,
    "limit_price_spread": null,
    "order_condition": "ETH-USDT@Binance ETH:PERP-USDT@Binance - 1 >",
    "order_condition_vars": {},
    "order_condition_expiry": null,
    "user": "13",
    "status": "SCHEDULED",
    "failure_reason": "",
    "completely_filled": true,
    "is_paused": false,
    "pct_filled": 100.0,
    "account_names": [
        "mock"
    ],
    "pairs": "BTC-USDT,BTC:PERP-USDT",
    "calculated_status": "COMPLETE",
    "sell_token_amount": "0.50000000000000000000, 46871.66540000000000000000",
    "buy_token": "USDT, BTC:PERP",
    "sell_token": "BTC, USDT"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity" %}

```
{
  "errors": [
    "Need at least one top level account or individual child order accounts",
    "Cannot have more than one of the qty fields: ['base_asset_qty', 'quote_asset_qty', 'sell_token_amount']"
  ]
}
```

{% endtab %}
{% endtabs %}

## Cancel Multi Orders

<mark style="color:green;">`POST`</mark> `/api/cancel_multi_orders/`

Cancel multi orders identified by the provided list of order IDs or custom order IDs, canceling all child orders and their active placements.  Must provide either `order_ids` or `custom_order_ids`.

**Request Body**

| Name               | Type           | Description                              |
| ------------------ | -------------- | ---------------------------------------- |
| `order_ids`        | array\[string] | list of multi order UUIDs                |
| `custom_order_ids` | array\[string] | array of user specified custom order IDs |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "message": "Multi orders canceled!"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "errors": ["Missing required field: order_ids or custom_order_ids"]
}
```

{% endtab %}

{% tab title="422" %}

```json
{
  "errors": ["Unexpected failure while cancelling order"]
}
```

{% endtab %}
{% endtabs %}

## Pause Multi Order

<mark style="color:green;">`POST`</mark> `/api/pause_multi_order/`

Pause a multi-order and all its child orders, canceling all active placements and stopping execution until resumed. The multi-order will maintain its current state and can be resumed later.

**Request Body**

| Name                                               | Type   | Description      |
| -------------------------------------------------- | ------ | ---------------- |
| `multi_order_id`<mark style="color:red;">\*</mark> | string | Name of the user |

#### Example Request

```
POST /api/pause_multi_order/
Authorization: Bearer <token>
Content-Type: application/json

{
  "multi_order_id": "6debb950-614a-4366-b73b-7d7574fd9e15"
}
```

**Response Codes**

{% tabs %}
{% tab title="202: Accepted" %}

```json
{
    "message": "Successfully paused multi order."
}
```

{% endtab %}

{% tab title="400: Bad Request" %}
Occurs when:

* The `multi_order_id` field is missing from the request body
* The multi-order is already paused or terminated

```json
{
    "error": "Multi Order already paused or terminated"
}
```

{% endtab %}

{% tab title="401: Unauthorized" %}
Occurs when:

* The user does not have permission to pause the specified multi-order (not the owner or not a superuser)

{% code title="Sample Error Message" %}

```json
{
    "error": "Unauthorized"
}
```

{% endcode %}
{% endtab %}

{% tab title="404: Not Found" %}
Occurs when:

* No multi-order exists with the given `multi_order_id`

{% code title="Sample Error Message" %}

```json
{
    "error": "No multi order found with given ID!"
}
```

{% endcode %}
{% endtab %}

{% tab title="422:  Unprocessable Entity" %}
{% code title="Sample Error Message" %}

```json
{
    "error": "Failed to pause all child orders: <error details>"
}
```

{% endcode %}
{% endtab %}

{% tab title="500" %}

```json
{
  "error": "Internal server error"
}
```

{% endtab %}
{% endtabs %}

## Resume Multi Order

<mark style="color:green;">`POST`</mark> `/api/resume_multi_order/`

Resume all legs of the multi order

**Request Body**

| Name                                               | Type   | Description                                           |
| -------------------------------------------------- | ------ | ----------------------------------------------------- |
| `multi_order_id`<mark style="color:red;">\*</mark> | string | UUID of the multi-order to resume. **Required Field** |

#### Example Request

```
POST /api/resume_multi_order/
Authorization: Bearer <token>
Content-Type: application/json

{
  "multi_order_id": "6debb950-614a-4366-b73b-7d7574fd9e15"
}
```

**Response Codes**

{% tabs %}
{% tab title="202: Accepted" %}

```json
{
    "message": "Successfully resumed multi order."
}
```

{% endtab %}

{% tab title="400: Bad Request" %}
Occurs when:

* The multi\_order\_id field is missing from the request body
* The multi-order is not currently paused

{% code title="Sample Error Messages" %}

```json
{
  "error": "Missing required field: multi_order_id"
}
```

{% endcode %}
{% endtab %}

{% tab title="401: Unauthorized" %}
Occurs when:

* The user does not have permission to resume the specified multi-order (not the owner or not a superuser)

{% code title="Sample Error Message" %}

```json
{
    "example": "Unauthorized"
}
```

{% endcode %}
{% endtab %}

{% tab title="422: Unprocessable Entity" %}
Occurs when:

* An error occurs while resuming one or more child orders
* There is a backend error during the resume operation

{% code title="Sample Error Message" %}

```json
{
    "error": "Failed to resume all child orders: <error details>"
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Get Placements

<mark style="color:blue;">`GET`</mark> `/api/placements/`

Returns placements (child orders) for a specific order.

### Query Parameters

| Name          | Type              | Description                                                                 |
| ------------- | ----------------- | --------------------------------------------------------------------------- |
| `order_id`    | string (UUID)     | UUID of the order to retrieve placements for. This is a required parameter. |
| `statuses`    | string            | comma separated list of statuses to filter by                               |
| `before`      | string (ISO 8601) | ISO 8601 timestamp (UTC). Filter placements created before this time.       |
| `after`       | string (ISO 8601) | ISO 8601 timestamp (UTC). Filter placements created after this time.        |
| `page_number` | number (integer)  | default: 1                                                                  |
| `page_size`   | number (integer)  | default: 100                                                                |

### **Request Body**

#### Top-Level Response Fields

| Field Name    | Type             | Nullable | Purpose                                        |
| ------------- | ---------------- | -------- | ---------------------------------------------- |
| `placements`  | array (object)   | No       | Array of placement objects                     |
| `page_number` | number (integer) | No       | Current page number                            |
| `page_size`   | number (integer) | No       | Number of items per page                       |
| `num_pages`   | number (integer) | No       | Total number of pages                          |
| `count`       | number (integer) | No       | Total count of placements matching the filters |

#### Placement Object Fields

| Field Name          | Type              | Nullable | Purpose                                                                                                                                           |
| ------------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                | string (UUID)     | No       | Unique placement identifier                                                                                                                       |
| `exchange`          | string            | Yes      | Exchange name where the placement was sent (e.g., "Bybit", "Deribit", "Binance"). Can be null for certain placement types                         |
| `qty`               | number (float)    | No       | Total placement quantity (decimal as number). This is the target quantity for the placement                                                       |
| `executed_qty`      | number (float)    | No       | Executed quantity for this placement (decimal as number). Amount that has been filled                                                             |
| `base_qty`          | number (float)    | Yes      | Base asset quantity (decimal as number, nullable). Used when tracking in base asset terms                                                         |
| `executed_base_qty` | number (float)    | Yes      | Executed base asset quantity (decimal as number, nullable). Base asset amount that has been filled                                                |
| `price`             | number (float)    | Yes      | Placement price (decimal as number, nullable). Limit price for limit orders, null for market orders                                               |
| `status`            | string            | No       | Placement status. Possible values: "PENDING", "ACTIVE", "FILLED", "CANCELED", "CANCEL\_PENDING", "FAILED", "MISSING"                              |
| `placement_type`    | string            | No       | Type of placement. Possible values: "TAKE" (market/taker order), "MAKE" (limit/maker order), "TAKE-PROFIT" (take profit order)                    |
| `passiveness`       | number (float)    | No       | Passiveness parameter (decimal as number). Controls how passive/aggressive the placement is (0.0 = most aggressive, higher values = more passive) |
| `failure_reason`    | string            | No       | Failure reason if placement failed (empty string if no failure). Provides details about why a placement failed                                    |
| `created_at`        | string (ISO 8601) | No       | Timestamp when the placement was created (UTC)                                                                                                    |
| `pct_filled`        | number (float)    | No       | Percentage filled (decimal as number, 0-100). Percentage of the placement quantity that has been executed                                         |
| `external_id`       | string            | No       | External exchange order ID (empty string if not yet assigned). The order ID returned by the exchange for this placement                           |

#### Notes

1. **Type Inconsistency:** Unlike other endpoints that return decimal values as strings, this endpoint returns `qty`, `executed_qty`, `price`, `pct_filled`, `base_qty`, and `executed_base_qty` as numbers (float). This is due to the `GetPlacements` implementation returning raw Decimal values which are serialized as numbers, rather than using `TrimmedDecimalField` like other endpoints.
2. **Empty Strings vs Null:** The `failure_reason` and `external_id` fields are strings that can be empty strings (`""`) rather than `null` when they have no value.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tread.fi/interacting-with-the-api/api-reference/multi-order.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.