Get all events by position

GET/positions/{positionId}/history

Get all events by positionTrading

What happened to one position, newest first: increases, partial and full closes, liquidation, force close, margin changes.

Funding payments are left out of this feed.
A force close carries the market event behind it, which is where the reason for it lives.

Base URL https://api.upscale.trade

Authorization

bearerhttp · bearerrequired

Personal API key, prefixed with usk_.

Parameters

Path

positionIdstring · uuidrequired

Position identifier. Its account must belong to the caller.

Example: 00000000-0000-4000-8000-000000000000

Examples

curl --request GET 'https://api.upscale.trade/positions/{positionId}/history' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'

const response = await fetch("https://api.upscale.trade/positions/{positionId}/history", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
});
console.log(response.status, await response.text());

import requests
 
response = requests.request(
    "GET",
    "https://api.upscale.trade/positions/{positionId}/history",
    headers={"Accept":"application/json","Authorization":"Bearer YOUR_API_KEY"},
    timeout=30,
)
print(response.status_code, response.text)

Responses

401

Unauthorized

403

The account belongs to another user (account_access_denied), or the request is authenticated with an API key while api_trading is disabled on the account (api_trading_not_enabled).

404

No position with this identifier.

429

Rate limit of the API key exceeded (api_key_rate_limit_exceeded). Retry-After says when to come back; the body carries the bucket (read / write), the window that tripped, its limit and retryAt.

defaultResponseapplication/json

Array of PositionEventResponse

idxstring[]required

Position identifier. Same value as txId.

Array items · string

string

View example

[
  "string"
]

txIdstring[]required

Position identifier. Kept for backward compatibility, always equal to idx.

Array items · string

string

View example

[
  "string"
]

versionnumberrequired

Revision of the position: incremented by every event applied to it.

Example: 0

openedAtstring · date-timerequired

When the position was opened.

Example: 2026-05-01T12:30:00.000Z

lastUpdatedAtstring · date-timerequired

When the last event was applied to the position.

Example: 2026-05-01T12:30:00.000Z

closedAtstring · date-time · nullablerequired

When the position was closed; null while it is still open.

Example: 2026-05-01T12:30:00.000Z

typestring · enumrequired

Direction of the position. Same value as direction.

Allowed: "long" "short"

Example: long

statusstring · enumrequired

Whether the position is still open, closed by the trader, or liquidated.

Allowed: "opened" "closed" "liquidated"

Example: opened

marketstring · uuidrequired

Market the position is held on.

pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

Example: 00000000-0000-4000-8000-000000000000

traderstring · uuidrequired

Trader account the position belongs to.

pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

Example: 00000000-0000-4000-8000-000000000000

sizestring · int32required

Position size in base asset units, fp9 raw.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

notionalstring · int32required

Open notional of the position in quote currency, fp9 raw — size at entry price.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

fractionstring · int32required

Always 0. Kept for backward compatibility.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

marginstring · int32required

Margin currently backing the position, fp9 raw. Moves with pnl, funding and manual margin changes.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

pnlstring · int32 · nullablerequired

Realised pnl accumulated over every event of the position, fp9 raw.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

fundingstring · int32 · nullablerequired

Funding paid (negative) or received (positive) over the life of the position, fp9 raw.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

rolloverFeestring · int32required

Always 0. Kept for backward compatibility.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

settlementOraclePricestring · int32required

Always 1000000000 (1.0). Kept for backward compatibility.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

feestring · int32required

Trading fees charged over the life of the position, fp9 raw.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

feeRatestring · int32required

Fee rate applied to the position, fp9 raw fraction (1000000 = 0.1%).

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

exchangedQuotestring · int32required

Quote amount exchanged by the most recent event, fp9 raw.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

exchangedBasestring · int32required

Base amount exchanged by the most recent event, fp9 raw.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

directionstring · enumrequired

Direction of the position.

Allowed: "long" "short"

Example: long

eventNamestring · enumrequired

Type of the most recent event applied to the position.

Allowed: "addMargin" "removeMargin" "closePosition" "increasePosition" "liquidate" "forceClose" "payFunding"

Example: addMargin

pnlInEventstring · int32required

Realised pnl of the most recent event, fp9 raw.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

rawPnlInEventstring · int32required

Realised pnl of the most recent event before the 60-second adjustment, fp9 raw. Differs from pnlInEvent only when the adjustment fired.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

profitAdjustmentAppliedbooleanrequired

Whether the 60-second adjustment capped the profit of the most recent event — inside a minute of an open or increase the position pnl cannot grow above what it was at that moment.

Example: true

holdingTimeMsstring[]required

How long the position was held before the most recent close, in milliseconds, counted from the open or the last increase. Null on events that are not closes.

Array items · string

string

View example

[
  "string"
]

feeInEventstring · int32required

Fee charged by the most recent event, fp9 raw.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

fundingInEventstring · int32required

Funding settled by the most recent event, fp9 raw.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

rolloverFeeInEventstring · int32required

Always 0. Kept for backward compatibility.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

executionFeeRatestring · int32required

Always 0. Kept for backward compatibility.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

executionFeeInEventstring · int32required

Always 0. Kept for backward compatibility.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

executionFeestring · int32required

Always 0. Kept for backward compatibility.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

timestampstring · date-timerequired

Timestamp of the most recent event. Same value as lastUpdatedAt.

Example: 2026-05-01T12:30:00.000Z

isOnchainbooleanrequired

Always true. Kept for backward compatibility.

Example: true

roestring · int32required

Return on equity of the position — realised pnl over the margin put up, fp9 raw fraction.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

scalpingCoefficientstring · int32required

Dynamic spread multiplier the position was charged, fp9 raw (1000000000 = 1.0). Above 1 when the trade fell inside the market scalping window.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

closeReasonstring[]required

Why the platform closed the position (for example weekly_session_risk_close). Null for positions closed by the trader and for open ones.

Array items · string

string

View example

[
  "string"
]

orderobject · nullablerequired

Order that produced this event; null for events the platform raised on its own, such as funding or a force close.

Object · 35 fields

idstring · uuidrequired

Order identifier.

pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

Example: 00000000-0000-4000-8000-000000000000

txIdstringrequired

Order identifier. Kept for backward compatibility, always equal to id.

Example: string

traderstring · uuidrequired

Trader account the order belongs to.

pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

Example: 00000000-0000-4000-8000-000000000000

marketstring · uuidrequired

Market the order is placed on.

pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

Example: 00000000-0000-4000-8000-000000000000

statusstring · enumrequired

Lifecycle state: active while it waits, executed once filled, canceled when cancelled by the trader or the platform, canceled_by_update when replaced by an edit, canceled_by_position when the position it was attached to went away, canceled_by_error when execution failed — see errorCode.

Allowed: "active" "canceled" "canceled_by_update" "canceled_by_error" "canceled_by_position" "executed"

Example: active

typestring · enumrequired

Order type. liquidation marks an order the engine raised itself.

Allowed: "market" "limit" "stop" "trailing_stop" "take" "stop_limit" "stop_market" "liquidation"

Example: market

directionstring · enumrequired

Order direction.

Allowed: "long" "short"

Example: long

triggerPricestring · int32required

Price at which the order fires, fp9 raw. 0 when the order carries no trigger.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

requestedTriggerPricestring · int32 · nullablerequired

Trigger price as requested, before the engine pushed it out to the minimum stop distance, fp9 raw. Null when the requested price was kept as is.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

stopPricestring · int32required

Trigger price of a stop_market / stop_limit order, fp9 raw; 0 for every other type.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

limitPricestring · int32required

Price the order is placed at once triggered, fp9 raw: the stop-limit price, falling back to the trigger price.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

stopTriggerPricestring · int32required

Stop-loss attached to the order, fp9 raw. 0 when none is attached.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

takeTriggerPricestring · int32required

Take-profit attached to the order, fp9 raw. 0 when none is attached.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

trailingStopActivationPricestring · int32required

Price at which a trailing stop starts trailing, fp9 raw. 0 when it trails from creation.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

trailingStopOffsetstring · int32required

Trailing distance as an absolute quote amount, fp9 raw. 0 when the distance is set as a percent.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

trailingStopOffsetPercentstring · int32required

Trailing distance as a fraction of price, fp9 raw. 0 when the distance is absolute.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

leveragestring · int32 · nullablerequired

Leverage of the order, fp9 raw. Null on close orders, which inherit the leverage of the position.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

indexstringrequired

Order identifier. Kept for backward compatibility, always equal to id.

Example: string

positionIdstring · nullablerequired

Position a close order is attached to. Null for orders that open or grow a position.

Example: string

parentOrderIdstring · nullablerequired

Order this one was spawned from: a stop or take created out of stopTriggerPrice / takeTriggerPrice, or the limit order a stop_limit turned into. Null when the order was submitted directly.

Example: string

expirationstring · date-time · nullablerequired

Always null. Kept for backward compatibility — orders do not expire on their own.

Example: 2026-05-01T12:30:00.000Z

amountstring · int32required

Size of the order, fp9 raw, in the unit its class uses: on an increase order a quote amount — the reserve while it waits, and what it actually spent once executed; on a close order (stop, take, trailing_stop) the base asset size it closes, as requested at creation.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

indexPricestring · int32 · nullablerequired

Index price the order executed at, fp9 raw. Null while the order has not executed.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

settlementOraclePricestring · int32required

Always 1000000000 (1.0). Kept for backward compatibility.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

createdAtstring · date-timerequired

When the order was accepted.

Example: 2026-05-01T12:30:00.000Z

errorstring · nullablerequired

Always null. Kept for backward compatibility — use errorCode.

Example: string

realizedPnlstring · int32 · nullablerequired

Pnl realised by this order, fp9 raw. Set only on an executed close order; null while pending and on orders that open or grow a position.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

rawRealizedPnlstring · int32 · nullablerequired

Realised pnl before the 60-second adjustment, fp9 raw. Differs from realizedPnl only when the adjustment fired.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

profitAdjustmentAppliedbooleanrequired

Whether the 60-second adjustment capped the profit of this order — inside a minute of an open or increase the position pnl cannot grow above what it was at that moment.

Example: true

executedAfterPausebooleanrequired

Whether the order executed after a market pause. Not set by the current engine — always false.

Example: true

sizeModestring · enumrequired

How the size was expressed on creation: quote sizes the order by amount, base sizes it by baseSize.

Allowed: "quote" "base"

Example: quote

baseSizestring · int32 · nullablerequired

Order size in base asset units, fp9 raw. Null for quote-sized orders.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

reservedAmountstring · int32 · nullablerequired

Quote amount reserved when the order with sizeMode=base was created, fp9 raw. Stays at the original reserve after execution, while amount is rewritten to what was spent. Null for quote-sized orders, where amount is the reserve.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

errorCodestring · nullablerequired

Why execution failed, set together with status canceled_by_error — for example insufficient_reserve_at_execution, order_below_min_notional, order_exceeds_market_depth or slippage_tolerance. Null otherwise.

Example: string

reasonstring · enum · nullablerequired

Why the platform cancelled the order itself, for example force_close or weekly_session_risk_close. Null for trader-driven cancellations.

Allowed: "force_close" "stop_accounts_fail" "stop_accounts_freeze" "stop_accounts_promote" "stop_accounts_manual" "weekly_session_risk_close" null

Example: force_close

View example

{
  "id": "00000000-0000-4000-8000-000000000000",
  "txId": "string",
  "trader": "00000000-0000-4000-8000-000000000000",
  "market": "00000000-0000-4000-8000-000000000000",
  "status": "active",
  "type": "market",
  "direction": "long",
  "triggerPrice": "1000000000",
  "requestedTriggerPrice": "1000000000",
  "stopPrice": "1000000000",
  "limitPrice": "1000000000",
  "stopTriggerPrice": "1000000000",
  "takeTriggerPrice": "1000000000",
  "trailingStopActivationPrice": "1000000000",
  "trailingStopOffset": "1000000000",
  "trailingStopOffsetPercent": "1000000000",
  "leverage": "1000000000",
  "index": "string",
  "positionId": "string",
  "parentOrderId": "string",
  "expiration": "2026-05-01T12:30:00.000Z",
  "amount": "1000000000",
  "indexPrice": "1000000000",
  "settlementOraclePrice": "1000000000",
  "createdAt": "2026-05-01T12:30:00.000Z",
  "error": "string",
  "realizedPnl": "1000000000",
  "rawRealizedPnl": "1000000000",
  "profitAdjustmentApplied": true,
  "executedAfterPause": true,
  "sizeMode": "quote",
  "baseSize": "1000000000",
  "reservedAmount": "1000000000",
  "errorCode": "string",
  "reason": "force_close"
}

[
  {
    "idx": [
      "string"
    ],
    "txId": [
      "string"
    ],
    "version": 0,
    "openedAt": "2026-05-01T12:30:00.000Z",
    "lastUpdatedAt": "2026-05-01T12:30:00.000Z",
    "closedAt": "2026-05-01T12:30:00.000Z",
    "type": "long",
    "status": "opened",
    "market": "00000000-0000-4000-8000-000000000000",
    "trader": "00000000-0000-4000-8000-000000000000",
    "size": "1000000000",
    "notional": "1000000000",
    "fraction": "1000000000",
    "margin": "1000000000",
    "pnl": "1000000000",
    "funding": "1000000000",
    "rolloverFee": "1000000000",
    "settlementOraclePrice": "1000000000",
    "fee": "1000000000",
    "feeRate": "1000000000",
    "exchangedQuote": "1000000000",
    "exchangedBase": "1000000000",
    "direction": "long",
    "eventName": "addMargin",
    "pnlInEvent": "1000000000",
    "rawPnlInEvent": "1000000000",
    "profitAdjustmentApplied": true,
    "holdingTimeMs": [
      "string"
    ],
    "feeInEvent": "1000000000",
    "fundingInEvent": "1000000000",
    "rolloverFeeInEvent": "1000000000",
    "executionFeeRate": "1000000000",
    "executionFeeInEvent": "1000000000",
    "executionFee": "1000000000",
    "timestamp": "2026-05-01T12:30:00.000Z",
    "isOnchain": true,
    "roe": "1000000000",
    "scalpingCoefficient": "1000000000",
    "closeReason": [
      "string"
    ],
    "order": {
      "id": "00000000-0000-4000-8000-000000000000",
      "txId": "string",
      "trader": "00000000-0000-4000-8000-000000000000",
      "market": "00000000-0000-4000-8000-000000000000",
      "status": "active",
      "type": "market",
      "direction": "long",
      "triggerPrice": "1000000000",
      "requestedTriggerPrice": "1000000000",
      "stopPrice": "1000000000",
      "limitPrice": "1000000000",
      "stopTriggerPrice": "1000000000",
      "takeTriggerPrice": "1000000000",
      "trailingStopActivationPrice": "1000000000",
      "trailingStopOffset": "1000000000",
      "trailingStopOffsetPercent": "1000000000",
      "leverage": "1000000000",
      "index": "string",
      "positionId": "string",
      "parentOrderId": "string",
      "expiration": "2026-05-01T12:30:00.000Z",
      "amount": "1000000000",
      "indexPrice": "1000000000",
      "settlementOraclePrice": "1000000000",
      "createdAt": "2026-05-01T12:30:00.000Z",
      "error": "string",
      "realizedPnl": "1000000000",
      "rawRealizedPnl": "1000000000",
      "profitAdjustmentApplied": true,
      "executedAfterPause": true,
      "sizeMode": "quote",
      "baseSize": "1000000000",
      "reservedAmount": "1000000000",
      "errorCode": "string",
      "reason": "force_close"
    }
  }
]