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

# Get an order

> Returns one of your orders by its ID. Pass `expand[]=timeline` for its history.



## OpenAPI

````yaml /openapi.yaml get /v1/orders/{id}
openapi: 3.1.0
info:
  title: Trading API
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
  version: '1'
  summary: Trade perpetual futures on Hyperliquid with plain HTTP requests.
  description: >
    The Trading API places market orders on Hyperliquid perpetual futures and
    reports your

    positions, fills and balance. You never sign anything, manage nonces or look
    up asset

    indexes: send a market, a side and a value in US dollars.


    Every request authenticates with an API key created on the account page:

    `Authorization: Bearer tapi_…`.
servers:
  - url: https://tradingapi.dev
    description: Production. Orders trade real money on Hyperliquid mainnet.
security:
  - apiKey: []
tags:
  - name: Markets
    description: The markets you can trade, with their rules and current prices.
  - name: Orders
    description: Place, preview, list and look up orders.
  - name: Positions
    description: Your open positions, and closing them.
  - name: Account
    description: Your balance, the calling key, fills and withdrawals.
paths:
  /v1/orders/{id}:
    get:
      tags:
        - Orders
      summary: Get an order
      description: >-
        Returns one of your orders by its ID. Pass `expand[]=timeline` for its
        history.
      operationId: getOrder
      parameters:
        - name: id
          in: path
          required: true
          description: The order ID, `ord_` followed by 26 characters.
          schema:
            type: string
            pattern: ^ord_[a-z2-7]{26}$
        - $ref: '#/components/parameters/Expand'
      responses:
        '200':
          description: The order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              examples:
                with_timeline:
                  $ref: '#/components/examples/OrderWithTimeline'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/OrderNotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    Expand:
      name: expand[]
      in: query
      required: false
      description: Extra detail to include. `timeline` adds the order's history.
      schema:
        type: string
        enum:
          - timeline
  schemas:
    Order:
      type: object
      required:
        - object
        - id
        - client_order_id
        - market
        - side
        - type
        - status
        - status_reason
        - requested_value
        - requested_percent
        - reduce_only
        - size
        - price
        - price_limit
        - time_in_force
        - filled_size
        - average_fill_price
        - filled_value
        - fee
        - position_effect
        - summary
        - notes
        - metadata
        - created_at
        - updated_at
        - completed_at
      properties:
        object:
          type: string
          const: order
        id:
          type: string
          description: Our ID for the order.
        client_order_id:
          $ref: '#/components/schemas/ClientOrderId'
        market:
          type: string
        side:
          $ref: '#/components/schemas/Side'
        type:
          $ref: '#/components/schemas/OrderType'
        status:
          $ref: '#/components/schemas/OrderStatus'
        status_reason:
          $ref: '#/components/schemas/StatusReason'
        requested_value:
          type:
            - string
            - 'null'
          description: >-
            The `value` you sent. `null` for a close by percent or of the whole
            position.
        requested_percent:
          type:
            - string
            - 'null'
          description: The `percent` of a close. `null` otherwise.
        reduce_only:
          type: boolean
        size:
          type:
            - string
            - 'null'
          description: >-
            The size sent to the market, in the market's units. `null` until the
            order is sized.
        price:
          type:
            - string
            - 'null'
          description: Your limit price as used. `null` for market orders.
        price_limit:
          type:
            - string
            - 'null'
          description: >-
            The worst price the order could fill at. For market orders, 0.5%
            from the price when it was placed.
        time_in_force:
          type: string
          enum:
            - ioc
          description: Always `ioc` (immediate or cancel) for now.
        filled_size:
          $ref: '#/components/schemas/Decimal'
        average_fill_price:
          type:
            - string
            - 'null'
        filled_value:
          type:
            - string
            - 'null'
          description: The USD value that filled.
        fee:
          type:
            - string
            - 'null'
          description: >-
            Total fees paid, in USD, exact to 6 decimals. Can arrive shortly
            after the order finishes.
        position_effect:
          $ref: '#/components/schemas/PositionEffect'
        summary:
          type: string
          description: >-
            What happened, in plain English. For people and language models;
            branch on fields, not on this text.
        notes:
          type: array
          items:
            $ref: '#/components/schemas/Note'
        metadata:
          $ref: '#/components/schemas/Metadata'
        timeline:
          type: array
          description: Present only with `expand[]=timeline`.
          items:
            $ref: '#/components/schemas/TimelineEntry'
        created_at:
          $ref: '#/components/schemas/Timestamp'
        updated_at:
          $ref: '#/components/schemas/Timestamp'
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the order reached a final status.
    ClientOrderId:
      type: string
      pattern: ^[A-Za-z0-9._:-]{1,64}$
      description: >-
        Your ID for the order, 1 to 64 characters of letters, digits, `.`, `_`,
        `:` and `-`. Unique per account, forever.
    Side:
      type: string
      enum:
        - buy
        - sell
    OrderType:
      type: string
      enum:
        - market
        - limit
      description: >
        `market` fills now at the best available prices, within 0.5% of the
        current price.

        `limit` fills now at your `price` or better; whatever cannot fill at
        once is canceled.
    OrderStatus:
      type: string
      enum:
        - pending
        - filled
        - canceled
        - rejected
      description: >
        `pending`: recorded, and possibly sent; the outcome is not known yet.

        `filled`: the whole size filled.

        `canceled`: filled partly or not at all; the rest found no price within
        the limit.

        `rejected`: refused; nothing filled.

        More statuses will be added. Treat a status you don't recognise as not
        finished.
    StatusReason:
      type:
        - object
        - 'null'
      required:
        - code
        - message
      description: Why an order is `canceled` or `rejected`. `null` otherwise.
      properties:
        code:
          type: string
          enum:
            - no_liquidity_in_limit
            - ioc_remainder
            - insufficient_balance
            - order_below_minimum
            - order_above_maximum
            - reduce_only_would_increase
            - no_position
            - market_unavailable
            - deadline_passed
            - refused_by_safeguards
            - not_sent
            - rejected_by_market
            - awaiting_market
        message:
          type: string
          description: What happened, in a sentence, with the numbers involved.
    Decimal:
      type: string
      description: >-
        A decimal number as a string, for example `"250.00"`. Requests also
        accept a JSON number.
      pattern: ^-?[0-9]+(\.[0-9]+)?$
    PositionEffect:
      type:
        - string
        - 'null'
      enum:
        - open
        - increase
        - reduce
        - close
        - flip
        - null
      description: What the order did to your position. `null` when nothing filled.
    Note:
      type: object
      required:
        - code
        - message
      description: >
        Something worth knowing about a response that did not stop it.
        `available_low`,

        `partial_fill_likely` and `trading_approval_expiring` appear on previews
        only.
      properties:
        code:
          type: string
          enum:
            - size_rounded
            - price_rounded
            - position_flipped
            - position_closed
            - available_low
            - partial_fill_likely
            - trading_approval_expiring
        message:
          type: string
    Metadata:
      type: object
      description: >-
        Up to 20 keys of your own, returned with the order and never
        interpreted. Keys up to 40 characters of letters, digits, `_`, `.` and
        `-`; string values up to 500 characters.
      maxProperties: 20
      additionalProperties:
        type: string
        maxLength: 500
    TimelineEntry:
      type: object
      required:
        - at
        - event
        - message
      properties:
        at:
          $ref: '#/components/schemas/Timestamp'
        event:
          type: string
          enum:
            - received
            - admitted
            - leverage_set
            - sent
            - filled
            - partially_filled
            - canceled
            - rejected
            - fees_recorded
        message:
          type: string
    Timestamp:
      type: string
      format: date-time
      description: >-
        RFC 3339 in UTC with milliseconds, for example
        `2026-09-27T14:30:00.123Z`.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
    Error:
      type: object
      required:
        - type
        - code
        - message
        - param
        - hint
        - details
        - errors
        - retryable
        - doc_url
      properties:
        type:
          type: string
          enum:
            - invalid_request
            - authentication
            - permission
            - not_found
            - conflict
            - unprocessable
            - rate_limited
            - unavailable
            - internal
          description: The kind of error. It determines the HTTP status.
        code:
          type: string
          description: >-
            A stable identifier for the error. Branch on this. New codes may be
            added.
        message:
          type: string
          description: What was wrong, with the values involved.
        param:
          type:
            - string
            - 'null'
          description: The request field at fault, as a JSON path, or `null`.
        hint:
          type:
            - string
            - 'null'
          description: One concrete way to fix the request.
        details:
          type: object
          description: The numbers and values the message refers to, as fields.
          additionalProperties: true
        errors:
          type: array
          description: Every field error, when `code` is `invalid_fields`. Empty otherwise.
          items:
            $ref: '#/components/schemas/Error'
        retryable:
          type: boolean
          description: Whether the same request can succeed later, unchanged.
        retry_after:
          $ref: '#/components/schemas/Timestamp'
          description: When a retry can succeed, if known.
        doc_url:
          type: string
          format: uri
  examples:
    OrderWithTimeline:
      summary: An order with its history
      value:
        object: order
        id: ord_7kq2m4x9h3v8r5t2w6y4n8p3za
        client_order_id: dca-btc-0927
        market: BTC
        side: buy
        type: market
        status: filled
        status_reason: null
        requested_value: '250.00'
        requested_percent: null
        reduce_only: false
        size: '0.00296'
        price: null
        price_limit: '84430'
        time_in_force: ioc
        filled_size: '0.00296'
        average_fill_price: '84012.4'
        filled_value: '248.68'
        fee: '0.360581'
        position_effect: open
        summary: >-
          Bought 0.00296 BTC for $248.68 at an average of $84,012.40 in 1 fill,
          fee $0.36. You asked for $250.00; the order was sized so it could not
          cost more even at its price limit of $84,430. You are now long 0.00296
          BTC.
        notes: []
        metadata:
          strategy: weekly-dca
        timeline:
          - at: '2026-09-27T14:30:00.123Z'
            event: received
            message: Buy $250.00 of BTC at market.
          - at: '2026-09-27T14:30:00.131Z'
            event: admitted
            message: 'Within this key''s limits: $157.40 of $1,000.00 left today.'
          - at: '2026-09-27T14:30:00.402Z'
            event: sent
            message: Buy 0.00296 BTC at up to $84,430, immediate or cancel.
          - at: '2026-09-27T14:30:00.618Z'
            event: filled
            message: 0.00296 BTC filled at an average of $84,012.40.
          - at: '2026-09-27T14:30:02.950Z'
            event: fees_recorded
            message: Fee $0.360581.
        created_at: '2026-09-27T14:30:00.123Z'
        updated_at: '2026-09-27T14:30:02.950Z'
        completed_at: '2026-09-27T14:30:00.618Z'
  responses:
    Unauthorized:
      description: No valid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalid_api_key:
              value:
                error:
                  type: authentication
                  code: invalid_api_key
                  message: This API key is not valid. It may have been revoked.
                  param: null
                  hint: >-
                    Send a current key as Authorization: Bearer tapi_…. Keys are
                    created and revoked on the account page.
                  details: {}
                  errors: []
                  retryable: false
                  doc_url: >-
                    https://docs.tradingapi.dev/api-reference/errors#invalid_api_key
    OrderNotFound:
      description: You have no order with this ID.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: >-
        The key made too many requests. Each key may make 10 requests at once,
        then 5 a second. Nothing was done; retry after `Retry-After` seconds.
      headers:
        Retry-After:
          description: The seconds to wait before retrying, always `1`.
          schema:
            type: string
            enum:
              - '1'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            rate_limited:
              value:
                error:
                  type: rate_limited
                  code: rate_limited
                  message: This key made too many requests; retry in 1 s.
                  param: null
                  hint: >-
                    Slow down: each key may make 10 requests at once, then 5 a
                    second.
                  details: {}
                  errors: []
                  retryable: true
                  retry_after: '2026-09-28T14:05:12.000Z'
                  doc_url: >-
                    https://docs.tradingapi.dev/api-reference/errors#rate_limited
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: tapi_…
      description: >-
        An API key from the account page, sent as `Authorization: Bearer
        tapi_…`.

````