Skip to main content

GET Order Lifecycle

Get order lifecycle by ID NT8​

Returns the complete lifecycle of a single order: every state transition recorded by the add-on (Submitted, Accepted, Working, PartFilled, Filled, Cancelled, Rejected, and so on), plus every inbound API submission attempt against the order, optionally merged with fills from NT8's in-memory Executions collection. Use this endpoint to reconcile orders end-to-end when a real-time WebSocket event was dropped, arrived out of order, or never made it to your application.

The add-on persists each event to its local SQLite the moment it happens, so the lifecycle is durable even across WebSocket disconnects or transient network failures. Default retention is 90 days.

Endpoint​

GET /v1/api/accounts/{account}/orders/{orderId}/lifecycle

Headers​

NameValue
Content-Typeapplication/json
AuthorizationBearer <token>

Path parameters​

NameTypeRequiredDescription
accountstringRequiredRequired by the URL pattern. The add-on does not filter by account, so any name (e.g. Sim101) resolves the same lifecycle. Included for routing symmetry with the other per-order endpoints.
orderIdstringRequiredNT8 OrderId or the original/xt id supplied at placement time. Either resolves correctly.

Query parameters​

NameTypeRequiredDescription
includeFillsbooleanOptionalDefault true. Merge fill events from NT8's in-memory Executions into the timeline.
includeRawbooleanOptionalDefault false. Include the full raw JSON snapshot for each event (verbose).
limitintOptionalDefault 200. Cap on rows returned. Server enforces a hard ceiling of 2000. If SQLite already returns limit rows, no fills will be merged. Bump limit if a single order has many lifecycle events and fills are needed.

Code examples​

import requests

token = 'my-secret-token'

url = "https://app.crosstrade.io/v1/api/accounts/Sim101/orders/50cca7b8051146c684087db511107983/lifecycle"
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
}
params = {
"includeFills": True,
"limit": 200
}

try:
response = requests.get(url, headers=headers, params=params)
print(f"Response Code: {response.status_code}, Response Text: {response.text}")
except Exception as e:
print(f"An error occurred: {e}")

Response​

{
"success": true,
"orderId": "50cca7b8051146c684087db511107983",
"originalOrderId": "myStrat_entry_42",
"account": "Sim101",
"count": 1,
"events": [
{
"timestamp": "2026-05-22T14:30:12.118Z",
"epoch": 1779114612118.0,
"source": "order_update",
"event": "Submitted",
"orderState": "Submitted",
"account": "Sim101",
"orderId": "50cca7b8051146c684087db511107983",
"originalOrderId": "myStrat_entry_42",
"correlationId": null,
"filled": 0,
"quantity": 1,
"avgFillPrice": 0.0,
"limitPrice": 5235.00,
"stopPrice": 0.0,
"reason": null,
"instrument": "ES 12-26",
"orderAction": "Buy",
"orderType": "Limit",
"timeInForce": "Day",
"name": null,
"ocoId": "",
"commission": null,
"slippage": null
}
]
}

Success field types​

Event fields vary by source. With includeRaw=true, stored order-update events can include raw, a JSON-encoded string containing the source snapshot. Parse that string separately if you need its fields. Merged execution events can omit raw even when requested.

FieldTypeDescription
successbooleantrue on success.
orderId, accountstringResolved order and account.
originalOrderIdstring or nullOriginal placement ID.
countintegerNumber of events.
eventsarray of objectsOrdered event timeline.
events[].timestamp, events[].source, events[].eventstringTime, emitter and event name.
events[].epochinteger or floatUnix milliseconds.
events[].account, events[].orderId, events[].instrument, events[].orderAction, events[].orderTypestringEvent identity and order attributes.
events[].executionIdstringPresent for merged execution events.
events[].originalOrderId, events[].orderState, events[].name, events[].ocoId, events[].timeInForcestring or nullOptional order metadata.
events[].correlationIdnull in capturesNon-null variants not captured.
events[].reasonstring or nullEvent reason, when available.
events[].rawstringOptional JSON-encoded source snapshot when includeRaw=true. Its contents vary by event source.
events[].filled, events[].quantityinteger or nullEvent quantities.
events[].avgFillPrice, events[].limitPrice, events[].stopPrice, events[].commission, events[].slippagefloat or nullEvent prices and costs.

Platform nuances​

Available in v1.13.2

Requires CrossTrade NT8 Add-On v1.13.2 or later. Older add-ons return an "Unknown API command" error. Update from the Add-On Changelog.

Source field​

The source column tells you which side of the system emitted the event:

  • api_received: the add-on accepted an inbound order-mutation API call (PlaceOrder, Cancel, Change, and so on). Captured before the call reaches NT8.
  • api_rejected: the add-on rejected the call before it reached NT8 (validation, missing account, malformed args). The reason field carries the error string.
  • order_update: NT8 fired its Account.OrderUpdate event. The orderState field carries the NT8 state string (Submitted, Working, PartFilled, Filled, Cancelled, Rejected, Expired, etc.).
  • execution: synthesized at read time from NT8's in-memory Executions. Only present when includeFills=true.

WebSocket API​

This request can also be made over the WebSocket API. Only orderId is required; account and the query parameters are accepted but optional (the add-on does not filter by account).

{
"action": "rpc",
"id": "my-request-id",
"api": "GetOrderLifecycle",
"args": {
"orderId": "50cca7b8051146c684087db511107983",
"includeFills": true
}
}