# Obtener el historial de todas las posiciones
`GET /positions/{accountId}/portfolio/history`
Todas las posiciones de la cuenta en todos los mercados, tanto abiertas como cerradas, las más recientes primero, con el recuento total para la paginación.
- Limitado a la fase en la que se encuentra actualmente la cuenta: no se devuelven las posiciones de una fase anterior.
## Autorización
bearer: http · bearer (obligatorio). Clave de API personal, con el prefijo `usk_`.
## Parámetros
- path: accountId (string · uuid; obligatorio). Identificador de la cuenta del trader. Debe pertenecer al solicitante.
Tipo: string · uuid
format: uuid
- query: limit (integer; opcional). Tamaño de página: cuántos registros devolver.
Tipo: integer
Ejemplo: 20
Predeterminado: 20
minimum: 1
maximum: 100
- query: offset (integer; opcional). Cuántos registros omitir antes de la página.
Tipo: integer
Ejemplo: 0
Predeterminado: 0
minimum: 0
maximum: 9007199254740991
## Ejemplo · cURL
```bash
curl --request GET 'https://api.upscale.trade/positions/{accountId}/portfolio/history' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY'
```
## Ejemplo · JavaScript
```javascript
const response = await fetch("https://api.upscale.trade/positions/{accountId}/portfolio/history", {
method: "GET",
headers: {
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_KEY"
},
});
console.log(response.status, await response.text());
```
## Ejemplo · Python
```python
import requests
response = requests.request(
"GET",
"https://api.upscale.trade/positions/{accountId}/portfolio/history",
headers={"Accept":"application/json","Authorization":"Bearer YOUR_API_KEY"},
timeout=30,
)
print(response.status_code, response.text)
```
## Respuesta 401
**401** — No autorizado
## Respuesta 403
**403** — La cuenta pertenece a otro usuario (`account_access_denied`), o la solicitud se autentica con una clave de API mientras `api_trading` está deshabilitado en la cuenta (`api_trading_not_enabled`).
## Respuesta 404
**404** — No hay ninguna cuenta con este identificador.
## Respuesta 429
**429** — Se superó el límite de velocidad de la clave de API (`api_key_rate_limit_exceeded`). `Retry-After` indica cuándo volver; el cuerpo incluye el bucket (`read` / `write`), la ventana que se activó, su límite y `retryAt`.
## Respuesta default · PositionsPaginatedResponse
**default** application/json — Respuesta
Tipo: object[]
[]Esquema: PositionsPaginatedResponse
[]Tipo: object
[]Campos obligatorios: data, totalCount
[]Tipos de campos obligatorios: data (object[]; obligatorio), totalCount (number; obligatorio)
- []data (object[]; obligatorio)
[]data ejemplo: [
{
"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"
}
]
[]data.Tipo: object[]
[]data.Página solicitada de posiciones, las más recientes primero.
[]data.[]Tipo: object
[]data.[]Campos obligatorios: idx, txId, version, openedAt, lastUpdatedAt, closedAt, type, status, market, trader, size, notional, fraction, margin, pnl, funding, rolloverFee, settlementOraclePrice, fee, feeRate, exchangedQuote, exchangedBase, direction, eventName, pnlInEvent, rawPnlInEvent, profitAdjustmentApplied, holdingTimeMs, feeInEvent, fundingInEvent, rolloverFeeInEvent, executionFeeRate, executionFeeInEvent, executionFee, timestamp, isOnchain, roe, scalpingCoefficient, closeReason
[]data.[]Tipos de campos obligatorios: idx (string · nullable; obligatorio), txId (string · nullable; obligatorio), version (number; obligatorio), openedAt (string · date-time; obligatorio), lastUpdatedAt (string · date-time; obligatorio), closedAt (string · date-time · nullable; obligatorio), type (string · enum; obligatorio), status (string · enum; obligatorio), market (string · uuid; obligatorio), trader (string · uuid; obligatorio), size (string · int32; obligatorio), notional (string · int32; obligatorio), fraction (string · int32; obligatorio), margin (string · int32; obligatorio), pnl (string · int32 · nullable; obligatorio), funding (string · int32 · nullable; obligatorio), rolloverFee (string · int32; obligatorio), settlementOraclePrice (string · int32; obligatorio), fee (string · int32; obligatorio), feeRate (string · int32; obligatorio), exchangedQuote (string · int32; obligatorio), exchangedBase (string · int32; obligatorio), direction (string · enum; obligatorio), eventName (string · enum; obligatorio), pnlInEvent (string · int32; obligatorio), rawPnlInEvent (string · int32; obligatorio), profitAdjustmentApplied (boolean; obligatorio), holdingTimeMs (string · nullable; obligatorio), feeInEvent (string · int32; obligatorio), fundingInEvent (string · int32; obligatorio), rolloverFeeInEvent (string · int32; obligatorio), executionFeeRate (string · int32; obligatorio), executionFeeInEvent (string · int32; obligatorio), executionFee (string · int32; obligatorio), timestamp (string · date-time; obligatorio), isOnchain (boolean; obligatorio), roe (string · int32; obligatorio), scalpingCoefficient (string · int32; obligatorio), closeReason (string · nullable; obligatorio)
- []data.[]idx (string · nullable; obligatorio)
[]data.[]idx ejemplo: string
[]data.[]idx.Tipo: string · nullable
[]data.[]idx.Identificador de la posición. Mismo valor que `txId`.
- []data.[]txId (string · nullable; obligatorio)
[]data.[]txId ejemplo: string
[]data.[]txId.Tipo: string · nullable
[]data.[]txId.Identificador de la posición. Se mantiene por compatibilidad hacia atrás, siempre igual a `idx`.
- []data.[]version (number; obligatorio)
[]data.[]version ejemplo: 0
[]data.[]version.Tipo: number
[]data.[]version.Revisión de la posición: incrementada por cada evento que se le aplica.
- []data.[]openedAt (string · date-time; obligatorio)
[]data.[]openedAt ejemplo: 2026-05-01T12:30:00.000Z
[]data.[]openedAt.Tipo: string · date-time
[]data.[]openedAt.Cuándo se abrió la posición.
[]data.[]openedAt.format: date-time
- []data.[]lastUpdatedAt (string · date-time; obligatorio)
[]data.[]lastUpdatedAt ejemplo: 2026-05-01T12:30:00.000Z
[]data.[]lastUpdatedAt.Tipo: string · date-time
[]data.[]lastUpdatedAt.Cuándo se aplicó el último evento a la posición.
[]data.[]lastUpdatedAt.format: date-time
- []data.[]closedAt (string · date-time · nullable; obligatorio)
[]data.[]closedAt ejemplo: 2026-05-01T12:30:00.000Z
[]data.[]closedAt.Tipo: string · date-time · nullable
[]data.[]closedAt.Cuándo se cerró la posición; null mientras sigue abierta.
[]data.[]closedAt.format: date-time
- []data.[]type (string · enum; obligatorio)
[]data.[]type ejemplo: long
[]data.[]type.Tipo: string · enum
[]data.[]type.Dirección de la posición. Mismo valor que `direction`.
[]data.[]type.Valores permitidos: ["long","short"]
- []data.[]status (string · enum; obligatorio)
[]data.[]status ejemplo: opened
[]data.[]status.Tipo: string · enum
[]data.[]status.Si la posición sigue abierta, fue cerrada por el trader o fue liquidada.
[]data.[]status.Valores permitidos: ["opened","closed","liquidated"]
- []data.[]market (string · uuid; obligatorio)
[]data.[]market ejemplo: 00000000-0000-4000-8000-000000000000
[]data.[]market.Tipo: string · uuid
[]data.[]market.Mercado en el que se mantiene la posición.
[]data.[]market.format: uuid
[]data.[]market.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})$
- []data.[]trader (string · uuid; obligatorio)
[]data.[]trader ejemplo: 00000000-0000-4000-8000-000000000000
[]data.[]trader.Tipo: string · uuid
[]data.[]trader.Cuenta del trader a la que pertenece la posición.
[]data.[]trader.format: uuid
[]data.[]trader.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})$
- []data.[]size (string · int32; obligatorio)
[]data.[]size ejemplo: 1000000000
[]data.[]size.Tipo: string · int32
[]data.[]size.Tamaño de la posición en unidades del activo base, fp9 sin procesar.
[]data.[]size.format: int32
[]data.[]size.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]notional (string · int32; obligatorio)
[]data.[]notional ejemplo: 1000000000
[]data.[]notional.Tipo: string · int32
[]data.[]notional.Nocional abierto de la posición en moneda de cotización, fp9 sin procesar — tamaño al precio de entrada.
[]data.[]notional.format: int32
[]data.[]notional.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]fraction (string · int32; obligatorio)
[]data.[]fraction ejemplo: 1000000000
[]data.[]fraction.Tipo: string · int32
[]data.[]fraction.Siempre `0`. Se mantiene por compatibilidad hacia atrás.
[]data.[]fraction.format: int32
[]data.[]fraction.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]margin (string · int32; obligatorio)
[]data.[]margin ejemplo: 1000000000
[]data.[]margin.Tipo: string · int32
[]data.[]margin.Margen que actualmente respalda la posición, fp9 sin procesar. Cambia con pnl, financiación y cambios manuales de margen.
[]data.[]margin.format: int32
[]data.[]margin.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]pnl (string · int32 · nullable; obligatorio)
[]data.[]pnl ejemplo: 1000000000
[]data.[]pnl.Tipo: string · int32 · nullable
[]data.[]pnl.Pnl realizado acumulado a lo largo de cada evento de la posición, fp9 sin procesar.
[]data.[]pnl.format: int32
[]data.[]pnl.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]funding (string · int32 · nullable; obligatorio)
[]data.[]funding ejemplo: 1000000000
[]data.[]funding.Tipo: string · int32 · nullable
[]data.[]funding.Financiación pagada (negativa) o recibida (positiva) durante la vida de la posición, fp9 en bruto.
[]data.[]funding.format: int32
[]data.[]funding.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]rolloverFee (string · int32; obligatorio)
[]data.[]rolloverFee ejemplo: 1000000000
[]data.[]rolloverFee.Tipo: string · int32
[]data.[]rolloverFee.Siempre `0`. Se mantiene por compatibilidad hacia atrás.
[]data.[]rolloverFee.format: int32
[]data.[]rolloverFee.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]settlementOraclePrice (string · int32; obligatorio)
[]data.[]settlementOraclePrice ejemplo: 1000000000
[]data.[]settlementOraclePrice.Tipo: string · int32
[]data.[]settlementOraclePrice.Siempre `1000000000` (1.0). Se mantiene por compatibilidad con versiones anteriores.
[]data.[]settlementOraclePrice.format: int32
[]data.[]settlementOraclePrice.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]fee (string · int32; obligatorio)
[]data.[]fee ejemplo: 1000000000
[]data.[]fee.Tipo: string · int32
[]data.[]fee.Comisiones de trading cobradas durante la vida de la posición, fp9 en bruto.
[]data.[]fee.format: int32
[]data.[]fee.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]feeRate (string · int32; obligatorio)
[]data.[]feeRate ejemplo: 1000000000
[]data.[]feeRate.Tipo: string · int32
[]data.[]feeRate.Tasa de comisión aplicada a la posición, fp9 fracción en bruto (`1000000` = 0.1%).
[]data.[]feeRate.format: int32
[]data.[]feeRate.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]exchangedQuote (string · int32; obligatorio)
[]data.[]exchangedQuote ejemplo: 1000000000
[]data.[]exchangedQuote.Tipo: string · int32
[]data.[]exchangedQuote.Importe de cotización intercambiado por el evento más reciente, fp9 en bruto.
[]data.[]exchangedQuote.format: int32
[]data.[]exchangedQuote.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]exchangedBase (string · int32; obligatorio)
[]data.[]exchangedBase ejemplo: 1000000000
[]data.[]exchangedBase.Tipo: string · int32
[]data.[]exchangedBase.Importe base intercambiado por el evento más reciente, fp9 en bruto.
[]data.[]exchangedBase.format: int32
[]data.[]exchangedBase.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]direction (string · enum; obligatorio)
[]data.[]direction ejemplo: long
[]data.[]direction.Tipo: string · enum
[]data.[]direction.Dirección de la posición.
[]data.[]direction.Valores permitidos: ["long","short"]
- []data.[]eventName (string · enum; obligatorio)
[]data.[]eventName ejemplo: addMargin
[]data.[]eventName.Tipo: string · enum
[]data.[]eventName.Tipo del evento más reciente aplicado a la posición.
[]data.[]eventName.Valores permitidos: ["addMargin","removeMargin","closePosition","increasePosition","liquidate","forceClose","payFunding"]
- []data.[]pnlInEvent (string · int32; obligatorio)
[]data.[]pnlInEvent ejemplo: 1000000000
[]data.[]pnlInEvent.Tipo: string · int32
[]data.[]pnlInEvent.Pnl realizado del evento más reciente, fp9 en bruto.
[]data.[]pnlInEvent.format: int32
[]data.[]pnlInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]rawPnlInEvent (string · int32; obligatorio)
[]data.[]rawPnlInEvent ejemplo: 1000000000
[]data.[]rawPnlInEvent.Tipo: string · int32
[]data.[]rawPnlInEvent.Pnl realizado del evento más reciente antes del ajuste de 60 segundos, fp9 en bruto. Difiere de `pnlInEvent` solo cuando se activó el ajuste.
[]data.[]rawPnlInEvent.format: int32
[]data.[]rawPnlInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]profitAdjustmentApplied (boolean; obligatorio)
[]data.[]profitAdjustmentApplied ejemplo: true
[]data.[]profitAdjustmentApplied.Tipo: boolean
[]data.[]profitAdjustmentApplied.Si el ajuste de 60 segundos limitó la ganancia del evento más reciente — dentro de un minuto de una apertura o un aumento de la posición, el pnl de la posición no puede crecer por encima de lo que era en ese momento.
- []data.[]holdingTimeMs (string · nullable; obligatorio)
[]data.[]holdingTimeMs ejemplo: string
[]data.[]holdingTimeMs.Tipo: string · nullable
[]data.[]holdingTimeMs.Cuánto tiempo se mantuvo la posición antes del cierre más reciente, en milisegundos, contado desde la apertura o el último incremento. Nulo en eventos que no son cierres.
- []data.[]feeInEvent (string · int32; obligatorio)
[]data.[]feeInEvent ejemplo: 1000000000
[]data.[]feeInEvent.Tipo: string · int32
[]data.[]feeInEvent.Comisión cobrada por el evento más reciente, fp9 en bruto.
[]data.[]feeInEvent.format: int32
[]data.[]feeInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]fundingInEvent (string · int32; obligatorio)
[]data.[]fundingInEvent ejemplo: 1000000000
[]data.[]fundingInEvent.Tipo: string · int32
[]data.[]fundingInEvent.Financiación liquidada por el evento más reciente, fp9 en bruto.
[]data.[]fundingInEvent.format: int32
[]data.[]fundingInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]rolloverFeeInEvent (string · int32; obligatorio)
[]data.[]rolloverFeeInEvent ejemplo: 1000000000
[]data.[]rolloverFeeInEvent.Tipo: string · int32
[]data.[]rolloverFeeInEvent.Siempre `0`. Se mantiene por compatibilidad hacia atrás.
[]data.[]rolloverFeeInEvent.format: int32
[]data.[]rolloverFeeInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]executionFeeRate (string · int32; obligatorio)
[]data.[]executionFeeRate ejemplo: 1000000000
[]data.[]executionFeeRate.Tipo: string · int32
[]data.[]executionFeeRate.Siempre `0`. Se mantiene por compatibilidad hacia atrás.
[]data.[]executionFeeRate.format: int32
[]data.[]executionFeeRate.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]executionFeeInEvent (string · int32; obligatorio)
[]data.[]executionFeeInEvent ejemplo: 1000000000
[]data.[]executionFeeInEvent.Tipo: string · int32
[]data.[]executionFeeInEvent.Siempre `0`. Se mantiene por compatibilidad hacia atrás.
[]data.[]executionFeeInEvent.format: int32
[]data.[]executionFeeInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]executionFee (string · int32; obligatorio)
[]data.[]executionFee ejemplo: 1000000000
[]data.[]executionFee.Tipo: string · int32
[]data.[]executionFee.Siempre `0`. Se mantiene por compatibilidad hacia atrás.
[]data.[]executionFee.format: int32
[]data.[]executionFee.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]timestamp (string · date-time; obligatorio)
[]data.[]timestamp ejemplo: 2026-05-01T12:30:00.000Z
[]data.[]timestamp.Tipo: string · date-time
[]data.[]timestamp.Marca de tiempo del evento más reciente. Mismo valor que `lastUpdatedAt`.
[]data.[]timestamp.format: date-time
- []data.[]isOnchain (boolean; obligatorio)
[]data.[]isOnchain ejemplo: true
[]data.[]isOnchain.Tipo: boolean
[]data.[]isOnchain.Siempre `true`. Se mantiene por compatibilidad con versiones anteriores.
- []data.[]roe (string · int32; obligatorio)
[]data.[]roe ejemplo: 1000000000
[]data.[]roe.Tipo: string · int32
[]data.[]roe.Rentabilidad sobre el capital de la posición — pnl realizado sobre el margen aportado, fp9 fracción sin procesar.
[]data.[]roe.format: int32
[]data.[]roe.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]scalpingCoefficient (string · int32; obligatorio)
[]data.[]scalpingCoefficient ejemplo: 1000000000
[]data.[]scalpingCoefficient.Tipo: string · int32
[]data.[]scalpingCoefficient.Multiplicador dinámico de spread que se aplicó a la posición, fp9 sin procesar (`1000000000` = 1.0). Por encima de 1 cuando la operación quedó dentro de la ventana de scalping del mercado.
[]data.[]scalpingCoefficient.format: int32
[]data.[]scalpingCoefficient.pattern: ^(?:-?[1-9][0-9]*|0)$
- []data.[]closeReason (string · nullable; obligatorio)
[]data.[]closeReason ejemplo: string
[]data.[]closeReason.Tipo: string · nullable
[]data.[]closeReason.Por qué la plataforma cerró la posición (por ejemplo, `weekly_session_risk_close`). Nulo para las posiciones cerradas por el trader y para las abiertas.
- []totalCount (number; obligatorio)
[]totalCount ejemplo: 0
[]totalCount.Tipo: number
[]totalCount.Número total de posiciones que coinciden con la solicitud, en todas las páginas.
Ejemplo
```json
[
{
"data": [
{
"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"
}
],
"totalCount": 0
}
]
```