> ## Documentation Index
> Fetch the complete documentation index at: https://docs.liftx.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Read holding-time analytics

> Distribution and P&L scatter from the same eligible closed-position cohort.

`read` is required for one authorized exact link without instrument restrictions.
Supply the link, environment, IANA `timezone` and `preset`. Optional `market`
and reporting `pair_id` narrow the cohort. Rolling presets include today and
forbid custom dates; `preset=custom` requires inclusive Gregorian `from`/`to`.

Positions are selected by final native exit and require verified execution
timing, final P\&L and positive executed entry cost. Duration starts at the first
native entry fill. P\&L percentage uses entry cost, not margin.

The eight histogram bins use exact P\&L sign. Scatter exact mode returns at most
2,000 individual positions; larger cohorts use at most 1,984 count-preserving
density groups with actual observed bounds. A group is not a position and does
not establish an exact mean or correlation. Preserve `state`, exclusions and
decimal strings; loading does not establish an empty cohort.

See [Account analytics](/api/templates-and-history#account-analytics).


## OpenAPI

````yaml api/openapi.json GET /v1/dashboard/holding-time
openapi: 3.1.0
info:
  title: Liftx integrations
  version: 1.0.0
  description: >-
    The Liftx API, TradingView webhook and session-owned integration settings.
    External access requires Pro or trial entitlement and is unmetered within
    bounded resource limits. Receipt acceptance does not confirm execution
    completion. MCP uses personal OAuth access and the same trading permissions
    and command receipts.
servers:
  - url: https://api.liftx.io
security: []
paths:
  /v1/dashboard/holding-time:
    get:
      summary: Get holding time and profitability
      description: >-
        Return both histogram and scatter for one committed eligible
        closed-position cohort, selected by final executed exit date. Requires
        native timing, canonical final P&L and a positive executed entry-cost
        basis. Duration is first native entry to final exit. pnl_percent uses
        entry cost, not margin. Supply an IANA timezone and a rolling preset
        through today, or preset=custom with inclusive Gregorian from/to.
        Presets forbid from/to; month arithmetic clamps month ends. Exact mode
        returns at most 2,000 positions; larger cohorts return at most 1,984
        count-preserving groups with actual bounds, not sampled trades. Respect
        state, excluded, as_of and revision. Narrow the selection if response
        admission is unavailable; never treat unavailable results as zero.
        Requires read permission for one authorized exact link with unrestricted
        instrument access. No account-wide or instrument-policy bypass; no
        trading action.
      operationId: get_v1_dashboard_holding_time
      parameters:
        - name: exchange_link_id
          in: query
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 9007199254740991
        - name: environment
          in: query
          required: true
          schema:
            type: string
            enum:
              - live
              - demo
        - name: market
          in: query
          required: false
          schema:
            type: string
            enum:
              - all
              - spot
              - futures
        - name: pair_id
          in: query
          required: false
          schema:
            type: string
            maxLength: 64
            description: >-
              Opaque reporting pair_id from liftx_analytics_list_assets; omit
              for All Assets. Not an executable instrument_id.
            pattern: ^([a-f0-9]{64})?$
        - name: timezone
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
            description: >-
              User-selected IANA timezone, e.g. Europe/London. Required; do not
              infer it from server time or locale.
        - name: preset
          in: query
          required: true
          schema:
            type: string
            enum:
              - week
              - month
              - 3months
              - 6months
              - year
              - custom
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date
            pattern: ^\d{4}-\d{2}-\d{2}$
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date
            pattern: ^\d{4}-\d{2}-\d{2}$
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HoldingAnalytics'
        default:
          description: >-
            Integration errors use Error; existing trading handlers retain their
            own JSON or text/plain error codec. Inspect status and content type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            text/plain:
              schema:
                type: string
      security:
        - ApiKey: []
components:
  schemas:
    HoldingAnalytics:
      type: object
      properties:
        scope:
          $ref: '#/components/schemas/AnalyticsScope'
        market:
          type: string
          enum:
            - all
            - spot
            - futures
        pair_id:
          type: string
        boundaries:
          type: array
          items:
            $ref: '#/components/schemas/ExecutionCalendarInterval'
        revision:
          type: string
        as_of:
          type: integer
          format: int64
        state:
          type: string
          enum:
            - ready
            - loading
            - updating
            - unavailable
        timezone:
          type: string
        calendar_generation:
          type: string
        from:
          type: string
          format: date
          pattern: ^\d{4}-\d{2}-\d{2}$
        to:
          type: string
          format: date
          pattern: ^\d{4}-\d{2}-\d{2}$
        count:
          type: integer
          format: int64
          minimum: 0
          maximum: 9007199254740991
        excluded:
          type: integer
          format: int64
          minimum: 0
          maximum: 9007199254740991
        histogram:
          type: array
          items:
            $ref: '#/components/schemas/HoldingHistogramBin'
          minItems: 8
          maxItems: 8
        scatter:
          $ref: '#/components/schemas/HoldingScatter'
      required:
        - scope
        - market
        - pair_id
        - boundaries
        - revision
        - as_of
        - state
        - timezone
        - calendar_generation
        - from
        - to
        - count
        - excluded
        - histogram
        - scatter
      additionalProperties: false
      description: >-
        One committed cohort for both charts: completed positions whose final
        native exit falls in the resolved interval and whose timing, final P&L
        and positive entry-cost basis are verified. Histogram outcome uses exact
        P&L sign. loading is not an empty cohort; updating retains coherent
        committed observations.
    Error:
      type: object
      properties:
        success:
          const: false
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
          required:
            - code
            - message
          additionalProperties: false
      required:
        - success
        - error
      additionalProperties: false
    AnalyticsScope:
      type: object
      properties:
        exchange_link_id:
          type: integer
          format: int64
          minimum: 0
          maximum: 9007199254740991
        environment:
          type: string
          enum:
            - live
            - demo
      required:
        - exchange_link_id
        - environment
      additionalProperties: false
    ExecutionCalendarInterval:
      type: object
      properties:
        from:
          type: integer
          format: int64
        to:
          type: integer
          format: int64
      required:
        - from
        - to
      additionalProperties: false
      description: >-
        Half-open UTC interval in Unix seconds, resolved from Gregorian civil
        dates in the supplied IANA timezone. Days need not contain 24 hours.
    HoldingHistogramBin:
      type: object
      properties:
        label:
          type: string
          enum:
            - <5m
            - 5–15m
            - 15–60m
            - 1–4h
            - 4–24h
            - 1–3d
            - 3–7d
            - 7d+
        profitable:
          type: integer
          format: int64
          minimum: 0
          maximum: 9007199254740991
        losing:
          type: integer
          format: int64
          minimum: 0
          maximum: 9007199254740991
        breakeven:
          type: integer
          format: int64
          minimum: 0
          maximum: 9007199254740991
      required:
        - label
        - profitable
        - losing
        - breakeven
      additionalProperties: false
    HoldingScatter:
      type: object
      properties:
        mode:
          type: string
          enum:
            - exact
            - density
        points:
          type: array
          items:
            $ref: '#/components/schemas/HoldingPoint'
          maxItems: 2000
        groups:
          type: array
          items:
            $ref: '#/components/schemas/HoldingDensityGroup'
          maxItems: 1984
      required:
        - mode
        - points
        - groups
      additionalProperties: false
    HoldingPoint:
      type: object
      properties:
        position_id:
          type: string
          format: uuid
        pair_id:
          type: string
        base:
          type: string
        quote:
          type: string
        market:
          type: integer
          format: int64
          enum:
            - 1
            - 2
        opened_at_ms:
          type: integer
          format: int64
        exited_at_ms:
          type: integer
          format: int64
        duration_ms:
          type: integer
          format: int64
          minimum: 0
        pnl_percent:
          type: string
          description: >-
            Decimal percentage string: 100 × canonical final quote P&L /
            positive executed entry cost. Preserve precision; not a leveraged or
            annualized return.
      required:
        - position_id
        - pair_id
        - base
        - quote
        - market
        - opened_at_ms
        - exited_at_ms
        - duration_ms
        - pnl_percent
      additionalProperties: false
    HoldingDensityGroup:
      type: object
      properties:
        duration_bin:
          type: integer
          format: int64
          minimum: 0
          maximum: 63
        return_bin:
          type: integer
          format: int64
          minimum: -15
          maximum: 15
        count:
          type: integer
          format: int64
          minimum: 0
          maximum: 9007199254740991
        duration_min_ms:
          type: integer
          format: int64
          minimum: 0
        duration_max_ms:
          type: integer
          format: int64
          minimum: 0
        pnl_percent_min:
          type: string
        pnl_percent_max:
          type: string
      required:
        - duration_bin
        - return_bin
        - count
        - duration_min_ms
        - duration_max_ms
        - pnl_percent_min
        - pnl_percent_max
      additionalProperties: false
      description: >-
        Count-preserving group with actual observed outer bounds. Does not
        represent an individual position; do not invent trade identities or
        infer a mean return from its bounds.
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: lx_api_<credential UUID>.<256-bit secret>

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.