---
title: "Trades"
description: "Read out the closed trades of a backtest."
canonical: https://www.quantconnect.com/docs/v2/cloud-platform/api-reference/backtest-management/read-backtest/trades
markdown: https://www.quantconnect.com/docs/v2/cloud-platform/api-reference/backtest-management/read-backtest/trades.md
language: python
source: https://github.com/QuantConnect/Documentation/tree/master/01%20Cloud%20Platform/99%20API%20Reference/05%20Backtest%20Management/02%20Read%20Backtest/04%20Trades
modified: 2026-11-18
index: https://www.quantconnect.com/llms.txt
---

# Trades

[Documentation](https://www.quantconnect.com/docs/v2.md) > [Cloud Platform](https://www.quantconnect.com/docs/v2/cloud-platform.md) > [API Reference](https://www.quantconnect.com/docs/v2/cloud-platform/api-reference.md) > [Backtest Management](https://www.quantconnect.com/docs/v2/cloud-platform/api-reference/backtest-management.md) > [Read Backtest](https://www.quantconnect.com/docs/v2/cloud-platform/api-reference/backtest-management/read-backtest.md) > Trades

> Code examples are shown in Python. Append `?lang=csharp` to this URL for the C# version of this page.

## Introduction

Read out the closed trades of a backtest.

## Description

This endpoint returns a page of closed trades with all their properties. To get all the closed trades of the backtest in one request, call the [/backtests/export/trades](https://www.quantconnect.com/docs/v2/cloud-platform/api-reference/backtest-management/read-backtest/export-trades.md) endpoint, which returns them as a CSV file. While the API prepares the closed trades, the response has a `status` of `loading` and a `progress` value. Send the request again until the response has no `status` field.

## Request

Fetch the closed trades of a backtest for the project Id, backtest Id and steps provided. The `/backtests/trades/read` API accepts requests in the following format:

| `ReadBacktestTradesRequest` Model - Request to read closed trades from a backtest. |  |
| --- | --- |
| start | `integer required example: 0` Starting index of the closed trades to be fetched. |
| end | `integer required example: 100` Last index of the closed trades to be fetched. |
| projectId | `integer required example: 23456789` Id of the project from which to read the backtest. |
| backtestId | `string required example: 26c7bb06b8487cff1c7b3c44652b30f1` Id of the backtest from which to read the closed trades. |
| Example | `{ "start": 0, "end": 100, "projectId": 23456789, "backtestId": "26c7bb06b8487cff1c7b3c44652b30f1" }` |

## Responses

The `/backtests/trades/read` API provides a response in the following format:

### 200 Success

| `LoadingResponse` Model - Response when the requested chart or orders are being generated. |  |
| --- | --- |
| progress | `number` Loading percentage of the data generation process. |
| status | `string Enum` Status of the data generation process. Options : ['loading'] |
| success | `boolean` Indicate if the API request was successful. |
| Example | `{ "progress": 0, "status": "loading", "success": true }` |

| `BacktestTradesResponse` Model - Contains the closed trades and the number of closed trades of the backtest in the request criteria. |  |
| --- | --- |
| trades | `ClosedTradeWithOrders Array` Collection of closed trades. |
| length | `integer` Total number of closed trades matching the request criteria. |
| success | `boolean` Indicate if the API request was successful. |
| errors | `string Array` List of errors with the API call. |
| Example | `{ "trades": [ { "id": "e1936b18-446b-4d57-95a6-6fd1a420e261", "symbols": [ { "value": "string", "id": "string", "permtick": "string" } ], "entryTime": "2021-11-26T15:18:27.693Z", "entryPrice": 0, "direction": 0, "quantity": 0, "exitTime": "2021-11-26T15:18:27.693Z", "exitPrice": 0, "profitLoss": 0, "totalFees": 0, "mae": 0, "mfe": 0, "duration": "string", "endTradeDrawdown": 0, "isWin": true, "orderIds": [ 0 ], "orders": [ { "id": 0, "contingentId": 0, "brokerId": [ "string" ], "symbol": { "value": "string", "id": "string", "permtick": "string" }, "limitPrice": 0, "stopPrice": 0, "stopTriggered": true, "price": 0, "priceCurrency": "string", "time": "2021-11-26T15:18:27.693Z", "createdTime": "2021-11-26T15:18:27.693Z", "lastFillTime": "2021-11-26T15:18:27.693Z", "lastUpdateTime": "2021-11-26T15:18:27.693Z", "canceledTime": "2021-11-26T15:18:27.693Z", "quantity": 0, "type": 0, "status": 0, "tag": "string", "securityType": 0, "direction": 0, "value": 0, "orderSubmissionData": { "bidPrice": 0, "askPrice": 0, "lastPrice": 0 }, "isMarketable": true, "properties": { "timeInForce": {} }, "events": [ { "algorithmId": "string", "symbol": "string", "symbolValue": "string", "symbolPermtick": "string", "orderId": 0, "orderEventId": 0, "id": "string", "status": "new", "orderFeeAmount": 0, "orderFeeCurrency": "string", "fillPrice": 0, "fillPriceCurrency": "string", "fillQuantity": 0, "direction": "buy", "message": "string", "isAssignment": true, "stopPrice": 0, "limitPrice": 0, "quantity": 0, "time": 0, "isInTheMoney": true } ], "trailingAmount": 0, "trailingAsPercentage": true, "groupOrderManager": { "id": 0, "quantity": 0, "count": 0, "limitPrice": 0, "orderIds": [ 0 ], "direction": 0 }, "triggerPrice": 0, "triggerTouched": true } ] } ], "length": 0, "success": true, "errors": [ "string" ] }` |

| `ClosedTradeWithOrders` Model - Represents a closed trade of a backtest or a live algorithm, with the orders that opened and closed it. |  |
| --- | --- |
| id | `string example: e1936b18-446b-4d57-95a6-6fd1a420e261` Unique identifier of the closed trade. |
| symbols | `Symbol Array` The securities involved in the trade. |
| entryTime | `string($date-time)` The date and time the trade was opened. |
| entryPrice | `number` The price at which the trade was opened (or the average price if multiple entries). |
| direction | `integer Enum` Direction of a trade. 0=Long, 1=Short. Options : [0, 1] |
| quantity | `number` The total unsigned quantity of the trade. |
| exitTime | `string($date-time)` The date and time the trade was closed. |
| exitPrice | `number` The price at which the trade was closed (or the average price if multiple exits). |
| profitLoss | `number` The gross profit/loss of the trade (as account currency). |
| totalFees | `number` The total fees associated with the trade (always positive value) (as account currency). |
| mae | `number` The Maximum Adverse Excursion (as account currency). |
| mfe | `number` The Maximum Favorable Excursion (as account currency). |
| duration | `string` The duration of the trade. |
| endTradeDrawdown | `number` The amount of profit given back before the trade was closed. |
| isWin | `boolean` Whether the trade closed at a profit. |
| orderIds | `integer Array` Ids of the orders that opened and closed the trade. |
| orders | `Order Array` The orders that opened and closed the trade. |
| Example | `{ "id": "e1936b18-446b-4d57-95a6-6fd1a420e261", "symbols": [ { "value": "string", "id": "string", "permtick": "string" } ], "entryTime": "2021-11-26T15:18:27.693Z", "entryPrice": 0, "direction": 0, "quantity": 0, "exitTime": "2021-11-26T15:18:27.693Z", "exitPrice": 0, "profitLoss": 0, "totalFees": 0, "mae": 0, "mfe": 0, "duration": "string", "endTradeDrawdown": 0, "isWin": true, "orderIds": [ 0 ], "orders": [ { "id": 0, "contingentId": 0, "brokerId": [ "string" ], "symbol": { "value": "string", "id": "string", "permtick": "string" }, "limitPrice": 0, "stopPrice": 0, "stopTriggered": true, "price": 0, "priceCurrency": "string", "time": "2021-11-26T15:18:27.693Z", "createdTime": "2021-11-26T15:18:27.693Z", "lastFillTime": "2021-11-26T15:18:27.693Z", "lastUpdateTime": "2021-11-26T15:18:27.693Z", "canceledTime": "2021-11-26T15:18:27.693Z", "quantity": 0, "type": 0, "status": 0, "tag": "string", "securityType": 0, "direction": 0, "value": 0, "orderSubmissionData": { "bidPrice": 0, "askPrice": 0, "lastPrice": 0 }, "isMarketable": true, "properties": { "timeInForce": {} }, "events": [ { "algorithmId": "string", "symbol": "string", "symbolValue": "string", "symbolPermtick": "string", "orderId": 0, "orderEventId": 0, "id": "string", "status": "new", "orderFeeAmount": 0, "orderFeeCurrency": "string", "fillPrice": 0, "fillPriceCurrency": "string", "fillQuantity": 0, "direction": "buy", "message": "string", "isAssignment": true, "stopPrice": 0, "limitPrice": 0, "quantity": 0, "time": 0, "isInTheMoney": true } ], "trailingAmount": 0, "trailingAsPercentage": true, "groupOrderManager": { "id": 0, "quantity": 0, "count": 0, "limitPrice": 0, "orderIds": [ 0 ], "direction": 0 }, "triggerPrice": 0, "triggerTouched": true } ] }` |

| `Symbol` Model - Represents a unique security identifier. This is made of two components, the unique SID and the Value. The value is the current ticker symbol while the SID is constant over the life of a security. |  |
| --- | --- |
| value | `string` The current symbol for this ticker. |
| id | `string` The security identifier for this symbol. |
| permtick | `string` The ticker at IPO for this security. |
| Example | `{ "value": "string", "id": "string", "permtick": "string" }` |

| `Order` Model - Order struct for placing new trade. |  |
| --- | --- |
| id | `integer` Order ID. |
| contingentId | `integer` Order Id to process before processing this order. |
| brokerId | `string Array` Brokerage Id for this order for when the brokerage splits orders into multiple pieces. |
| symbol | `Symbol object` Represents a unique security identifier. This is made of two components, the unique SID and the Value. The value is the current ticker symbol while the SID is constant over the life of a security. |
| limitPrice | `number` Limit price of the Order. |
| stopPrice | `number` Stop price of the Order. |
| stopTriggered | `boolean` Indicates if the stop price has been reached, so the limit order has been triggered. |
| price | `number` Price of the Order. |
| priceCurrency | `string` Currency for the order price. |
| time | `string($date-time)` Gets the UTC time the order was created. |
| createdTime | `string($date-time)` Gets the UTC time this order was created. Alias for Time. |
| lastFillTime | `string($date-time)` Gets the UTC time the last fill was received, or null if no fills have been received. |
| lastUpdateTime | `string($date-time)` Gets the UTC time this order was last updated, or null if the order has not been updated. |
| canceledTime | `string($date-time)` Gets the UTC time this order was canceled, or null if the order was not canceled. |
| quantity | `number` Number of shares to execute. |
| type | `integer Enum` Order type. 0=Market, 1=Limit, 2=StopMarket, 3=StopLimit, 4=MarketOnOpen, 5=MarketOnClose, 6=OptionExercise, 7=LimitIfTouched, 8=ComboMarket, 9=ComboLimit, 10=ComboLegLimit, 11=TrailingStop. Options : [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11] |
| status | `integer Enum` Status of the Order. 0=New, 1=Submitted, 2=PartiallyFilled, 3=Filled, 5=Canceled, 6=None, 7=Invalid, 8=CancelPending, 9=UpdateSubmitted. Options : [0, 1, 2, 3, 5, 6, 7, 8, 9] |
| tag | `string` Tag the order with some custom data. |
| securityType | `integer Enum` Type of tradable security / underlying asset. 0=Base, 1=Equity, 2=Option, 3=Commodity, 4=Forex, 5=Future, 6=Cfd, 7=Crypto, 8=FutureOption, 9=Index, 10=IndexOption, 11=CryptoFuture. Options : [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11] |
| direction | `integer Enum` Order Direction Property based off Quantity. 0=Buy, 1=Sell, 2=Hold. Options : [0, 1, 2] |
| value | `number` Gets the executed value of this order. If the order has not yet filled, then this will return zero. |
| orderSubmissionData | `OrderSubmissionData object` Stores time and price information available at the time an order was submitted. |
| isMarketable | `boolean` Returns true if the order is a marketable order. |
| properties | `OrderProperties object` Additional properties of the order. |
| events | `OrderEvent Array` The order events. |
| trailingAmount | `number` Trailing amount for a trailing stop order. |
| trailingAsPercentage | `boolean` Determines whether the trailingAmount is a percentage or an absolute currency value. |
| groupOrderManager | `GroupOrderManager object` Manager of a group of orders. |
| triggerPrice | `number` The price which, when touched, will trigger the setting of a limit order at limitPrice. |
| triggerTouched | `boolean` Whether or not the triggerPrice has been touched. |
| Example | `{ "id": 0, "contingentId": 0, "brokerId": [ "string" ], "symbol": { "value": "string", "id": "string", "permtick": "string" }, "limitPrice": 0, "stopPrice": 0, "stopTriggered": true, "price": 0, "priceCurrency": "string", "time": "2021-11-26T15:18:27.693Z", "createdTime": "2021-11-26T15:18:27.693Z", "lastFillTime": "2021-11-26T15:18:27.693Z", "lastUpdateTime": "2021-11-26T15:18:27.693Z", "canceledTime": "2021-11-26T15:18:27.693Z", "quantity": 0, "type": 0, "status": 0, "tag": "string", "securityType": 0, "direction": 0, "value": 0, "orderSubmissionData": { "bidPrice": 0, "askPrice": 0, "lastPrice": 0 }, "isMarketable": true, "properties": { "timeInForce": {} }, "events": [ { "algorithmId": "string", "symbol": "string", "symbolValue": "string", "symbolPermtick": "string", "orderId": 0, "orderEventId": 0, "id": "string", "status": "new", "orderFeeAmount": 0, "orderFeeCurrency": "string", "fillPrice": 0, "fillPriceCurrency": "string", "fillQuantity": 0, "direction": "buy", "message": "string", "isAssignment": true, "stopPrice": 0, "limitPrice": 0, "quantity": 0, "time": 0, "isInTheMoney": true } ], "trailingAmount": 0, "trailingAsPercentage": true, "groupOrderManager": { "id": 0, "quantity": 0, "count": 0, "limitPrice": 0, "orderIds": [ 0 ], "direction": 0 }, "triggerPrice": 0, "triggerTouched": true }` |

| `OrderSubmissionData` Model - Stores time and price information available at the time an order was submitted. |  |
| --- | --- |
| bidPrice | `number` The bid price at order submission time. |
| askPrice | `number` The ask price at order submission time. |
| lastPrice | `number` The current price at order submission time. |
| Example | `{ "bidPrice": 0, "askPrice": 0, "lastPrice": 0 }` |

| `OrderProperties` Model - Additional properties of the order |  |
| --- | --- |
| timeInForce | `object` Defines the length of time over which an order will continue working before it is cancelled. |
| Example | `{ "timeInForce": {} }` |

| `OrderEvent` Model - Change in an order state applied to user algorithm portfolio |  |
| --- | --- |
| algorithmId | `string` Algorithm Id, BacktestId or DeployId. |
| symbol | `string` Easy access to the order symbol associated with this event. |
| symbolValue | `string` The current symbol for this ticker; It is a user friendly symbol representation. |
| symbolPermtick | `string` The original symbol used to generate this symbol. |
| orderId | `integer` Id of the order this event comes from. |
| orderEventId | `integer` The unique order event id for each order. |
| id | `string` The unique order event Id for each order. |
| status | `string Enum` Status of the Order. Options : ['new', 'submitted', 'partiallyFilled', 'filled', 'canceled', 'none', 'invalid', 'cancelPending', 'updateSubmitted'] |
| orderFeeAmount | `number` The fee amount associated with the order. |
| orderFeeCurrency | `string` The fee currency associated with the order. |
| fillPrice | `number` Fill price information about the order. |
| fillPriceCurrency | `string` Currency for the fill price. |
| fillQuantity | `number` Number of shares of the order that was filled in this event. |
| direction | `string Enum` Direction of the order. Options : ['buy', 'sell', 'hold'] |
| message | `string` Any message from the exchange. |
| isAssignment | `boolean` True if the order event is an assignment. |
| stopPrice | `number` The current stop price. |
| limitPrice | `number` The current limit price. |
| quantity | `number` The current order quantity. |
| time | `number` The time of this event in unix timestamp. |
| isInTheMoney | `boolean` True if the order event's option is In-The-Money (ITM). |
| Example | `{ "algorithmId": "string", "symbol": "string", "symbolValue": "string", "symbolPermtick": "string", "orderId": 0, "orderEventId": 0, "id": "string", "status": "new", "orderFeeAmount": 0, "orderFeeCurrency": "string", "fillPrice": 0, "fillPriceCurrency": "string", "fillQuantity": 0, "direction": "buy", "message": "string", "isAssignment": true, "stopPrice": 0, "limitPrice": 0, "quantity": 0, "time": 0, "isInTheMoney": true }` |

| `OrderDirection` Model - Direction of the order. |  |
| --- | --- |
| GroupOrderManager | `string Enum` Direction of the order. Options : ['buy', 'sell', 'hold'] |
| Example | `{ "GroupOrderManager": "buy" }` |

| `GroupOrderManager` Model - Manager of a group of orders. |  |
| --- | --- |
| id | `integer` The unique order group Id. |
| quantity | `number` The group order quantity. |
| count | `integer` The total order count associated with this order group. |
| limitPrice | `number` The limit price associated with this order group if any. |
| orderIds | `integer Array` The order Ids in this group. |
| direction | `integer` Order Direction Property based off Quantity. |
| Example | `{ "id": 0, "quantity": 0, "count": 0, "limitPrice": 0, "orderIds": [ 0 ], "direction": 0 }` |

### 401 Authentication Error

| `UnauthorizedError` Model - Unauthorized response from the API. Key is missing, invalid, or timestamp is too old for hash. |  |
| --- | --- |
| www_authenticate | `string` Header |

## Examples

The following example demonstates creating, reading, updating, deleting, and listing backtests of a project through the cloud API.

```
from base64 import b64encode
from hashlib import sha256
from time import time
from requests import get, post
BASE_URL = 'https://www.quantconnect.com/api/v2/'

# You need to replace these with your actual credentials.
# You can request your credentials at https://www.quantconnect.com/settings/
# You can find our organization ID at https://www.quantconnect.com/organization/
USER_ID = 0
API_TOKEN = '____'
ORGANIZATION_ID = '____'

def get_headers():
    # Get timestamp
    timestamp = f'{int(time())}'
    time_stamped_token = f'{API_TOKEN}:{timestamp}'.encode('utf-8')

    # Get hased API token
    hashed_token = sha256(time_stamped_token).hexdigest()
    authentication = f'{USER_ID}:{hashed_token}'.encode('utf-8')
    authentication = b64encode(authentication).decode('ascii')

    # Create headers dictionary.
    return {
        'Authorization': f'Basic {authentication}',
        'Timestamp': timestamp
    }

# Authenticate to verify credentials
response = post(f'{BASE_URL}/authenticate', headers = get_headers())
print(response.json())

# --------------------

### Create Backtest
# Define placeholder compilation ID (replace with actual value)
compile_id = "compile_id..."
# Send a POST request to the /backtests/create endpoint to create a backtest
response = post(f'{BASE_URL}/backtests/create', headers=get_headers(), json={
    "projectId": project_id,  # ID of the project to backtest
    "compileId": compile_id,  # Compilation ID for the backtest
    "backtestName": f"Backtest {int(time())}"  # Unique name for the backtest using current timestamp
})
# Parse the JSON response into python managable dict
result = response.json()
# Extract the backtest ID from the response
backtest_id = result['backtest']['backtestId']
# Check if the request was successful and print the result
if result['success']:
    print("Backtest Created Successfully:")
    print(result)

### Read Backtest Statistics
# Prepare data payload to read backtest statistics
payload = {
    "projectId": project_id,  # ID of the project
    "backtestId": backtest_id  # ID of the backtest to read
}
# Send a POST request to the /backtests/read endpoint to get statistics
response = post(f'{BASE_URL}/backtests/read', headers=get_headers(), json=payload)
# Parse the JSON response into python managable dict
result = response.json()
# Check if the request was successful and print the statistics
if result['success']:
    print("Backtest Statistics:")
    print(result)

### Read Backtest Logs
# Prepare data payload to read the first 200 log lines
payload = {
    "projectId": project_id,  # ID of the project
    "backtestId": backtest_id,  # ID of the backtest to read
    "start": 0,  # Start line (inclusive)
    "end": 200,  # End line (exclusive), at most 200 lines per request
    "query": None  # Keyword to filter the lines, or None to read all of them
}
# Send a POST request to the /backtests/read/log endpoint to get the logs
response = post(f'{BASE_URL}/backtests/read/log', headers=get_headers(), json=payload)
# Parse the JSON response into python managable dict
result = response.json()
# Check if the request was successful and print the logs
if result['success']:
    print("Backtest Logs:")
    print(result)

### Update Backtest
# Send a POST request to the /backtests/update endpoint to update backtest details
response = post(f'{BASE_URL}/backtests/update', headers=get_headers(), json={
    "projectId": project_id,  # ID of the project
    "backtestId": backtest_id,  # ID of the backtest to update
    "name": f"Backtest_{backtest_id}",  # New name for the backtest
    "note": "The new backtest name is awesome!"  # Additional note
})
# Parse the JSON response into python managable dict
result = response.json()
# Check if the request was successful and print the result
if result['success']:
    print("Backtest Updated Successfully:")
    print(result)

### Delete Backtest
# Prepare data payload to delete the backtest
payload = {
    "projectId": project_id,  # ID of the project
    "backtestId": backtest_id  # ID of the backtest to delete
}
# Send a POST request to the /backtests/delete endpoint to delete the backtest
response = post(f'{BASE_URL}/backtests/delete', headers=get_headers(), json=payload)
# Parse the JSON response into python managable dict
result = response.json()
# Check if the request was successful and print the result
if result['success']:
    print("Backtest Deleted Successfully:")
    print(result)

### List Backtests
# Prepare data payload to list backtests with statistics
payload = {
    "projectId": project_id,  # ID of the project
    "includeStatistics": True  # Include statistics in the response
}
# Send a POST request to the /backtests/list endpoint to list backtests
response = post(f'{BASE_URL}/backtests/list', headers=get_headers(), json=payload)
# Parse the JSON response into python managable dict
result = response.json()
# Check if the request was successful and print the list
if result['success']:
    print("List of Backtests:")
    print(result)

### Export Orders
# Download the orders of the backtest as a CSV file
payload = {
    "backtestId": backtest_id  # ID of the backtest
}
response = post(f'{BASE_URL}/backtests/export/orders', headers=get_headers(), json=payload)
with open(f'orders-{backtest_id}.csv', 'w', newline='') as file:
    file.write(response.text)

### Export Trades
# Download the closed trades of the backtest as a CSV file
payload = {
    "backtestId": backtest_id  # ID of the backtest
}
response = post(f'{BASE_URL}/backtests/export/trades', headers=get_headers(), json=payload)
with open(f'trades-{backtest_id}.csv', 'w', newline='') as file:
    file.write(response.text)

### Export Insights
# Download the insights of the backtest as a JSON file
payload = {
    "backtestId": backtest_id  # ID of the backtest
}
response = post(f'{BASE_URL}/backtests/export/insights', headers=get_headers(), json=payload)
with open(f'insights-{backtest_id}.json', 'w', newline='') as file:
    file.write(response.text)

### Export Logs
# Download the logs of the backtest as a text file
payload = {
    "projectId": project_id,  # ID of the project
    "backtestId": backtest_id  # ID of the backtest
}
response = post(f'{BASE_URL}/backtests/export/logs', headers=get_headers(), json=payload)
with open(f'logs-{backtest_id}.txt', 'w', newline='') as file:
    file.write(response.text)
```
