Skip to main content

Search for Trades

API URL: POST https://api.topstepx.com/api/Trade/search

API Reference: /api/Trade/search

Description​

Search for trades from the request parameters.

Each trade is one leg of an execution, for simulated and live accounts alike:

  • An opening leg has a null profitAndLoss (a half-turn). A closing leg carries the gross profitAndLoss of the position it closes.
  • An execution returns one trade per open position it closes, plus an opening trade for any quantity left over when it reverses the position. The first keeps the original id; the others get new ids with the same orderId, price and creationTimestamp. On a live account every leg carries its execution's fillId, so group legs by fillId to rebuild executions; fillId is null for simulated accounts, whose trades group by orderId. fees and commissions are split across the legs and sum to the execution's total.
  • A live trade can appear shortly after its execution and be updated after it is first returned. When an execution arrives late, is corrected or is busted by the exchange, its legs are recalculated: existing legs keep their ids, a new leg gets a new id, and a leg that no longer applies comes back with voided set to true. Search again, or follow GatewayUserTrade updates, to stay current.
  • A voided trade no longer counts. If you store trades by id, keep it so your copy is marked voided, but leave it out of position, profit and fee totals.

Parameters​

NameTypeDescriptionRequiredNullable
accountIdintegerThe account ID.Requiredfalse
startTimestampdatetimeThe start of the timestamp filter.Requiredfalse
endTimestampdatetimeThe end of the timestamp filter.Optionaltrue

Example Usage​

Example Request​

curl -X 'POST' \
  'https://api.topstepx.com/api/Trade/search' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountId": 203,
    "startTimestamp": "2025-01-20T15:47:39.882Z",
    "endTimestamp": "2025-01-30T15:47:39.882Z"
  }'

Example Response​

{
    "trades": [
        {
            "id": 8604,
            "accountId": 203,
            "contractId": "CON.F.US.EP.H25",
            "creationTimestamp": "2025-01-21T16:13:52.523293+00:00",
            "price": 6065.250000000,
            "profitAndLoss": 50.000000000,
            "fees": 1.4000,
            "commissions": 0.3500,
            "side": 1,
            "size": 1,
            "voided": false,
            "orderId": 14328,
            "fillId": null    //set on live accounts only
        },
        {
            "id": 8603,
            "accountId": 203,
            "contractId": "CON.F.US.EP.H25",
            "creationTimestamp": "2025-01-21T16:13:04.142302+00:00",
            "price": 6064.250000000,
            "profitAndLoss": null,    //a null value indicates a half-turn trade
            "fees": 1.4000,
            "commissions": 0.3500,
            "side": 0,
            "size": 1,
            "voided": false,
            "orderId": 14326,
            "fillId": null    //set on live accounts only
        }
    ],
    "success": true,
    "errorCode": 0,
    "errorMessage": null
}