> ## 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.

# List fills

> Returns your executions, newest first, read live from the exchange.



## OpenAPI

````yaml /openapi.yaml get /v1/fills
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/fills:
    get:
      tags:
        - Account
      summary: List fills
      description: Returns your executions, newest first, read live from the exchange.
      operationId: listFills
      parameters:
        - name: market
          in: query
          required: false
          description: Only fills in this market.
          schema:
            type: string
        - name: order_id
          in: query
          required: false
          description: Only fills of this order.
          schema:
            type: string
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of fills.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FillList'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: How many items to return, from 1 to 100.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    Cursor:
      name: cursor
      in: query
      required: false
      description: The `next_cursor` from the previous page.
      schema:
        type: string
  schemas:
    FillList:
      type: object
      required:
        - object
        - data
        - next_cursor
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Fill'
        next_cursor:
          type:
            - string
            - 'null'
    Fill:
      type: object
      required:
        - object
        - order_id
        - client_order_id
        - market
        - side
        - size
        - price
        - value
        - fee
        - realized_pnl
        - executed_at
      properties:
        object:
          type: string
          const: fill
        order_id:
          type:
            - string
            - 'null'
        client_order_id:
          type:
            - string
            - 'null'
        market:
          type: string
        side:
          $ref: '#/components/schemas/Side'
        size:
          type: string
        price:
          type: string
        value:
          type: string
        fee:
          type: string
        realized_pnl:
          type: string
          description: Profit or loss this fill realized by reducing a position, in USD.
        executed_at:
          $ref: '#/components/schemas/Timestamp'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
    Side:
      type: string
      enum:
        - buy
        - sell
    Timestamp:
      type: string
      format: date-time
      description: >-
        RFC 3339 in UTC with milliseconds, for example
        `2026-09-27T14:30:00.123Z`.
    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
  responses:
    InvalidRequest:
      description: >-
        The request is malformed or breaks a rule. Nothing was recorded; fix it
        and send it again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalid_fields:
              summary: Several fields at once
              value:
                error:
                  type: invalid_request
                  code: invalid_fields
                  message: 3 fields are invalid.
                  param: null
                  hint: Fix each field listed in errors.
                  details: {}
                  errors:
                    - type: invalid_request
                      code: invalid_value
                      message: >-
                        side is "long". Orders use "buy" or "sell"; "long"
                        describes a position.
                      param: side
                      hint: 'To open a long, send "side": "buy".'
                      details: {}
                      errors: []
                      retryable: false
                      doc_url: >-
                        https://docs.tradingapi.dev/api-reference/errors#invalid_value
                    - type: invalid_request
                      code: unknown_field
                      message: amount is not a field of this request.
                      param: amount
                      hint: Did you mean value? It is the order's size in USD.
                      details: {}
                      errors: []
                      retryable: false
                      doc_url: >-
                        https://docs.tradingapi.dev/api-reference/errors#unknown_field
                    - type: invalid_request
                      code: missing_field
                      message: value is required.
                      param: value
                      hint: >-
                        Send how much to buy or sell in USD, for example
                        "value": "25.00".
                      details: {}
                      errors: []
                      retryable: false
                      doc_url: >-
                        https://docs.tradingapi.dev/api-reference/errors#missing_field
                  retryable: false
                  doc_url: >-
                    https://docs.tradingapi.dev/api-reference/errors#invalid_fields
            order_below_minimum:
              summary: Under the minimum after rounding
              value:
                error:
                  type: invalid_request
                  code: order_below_minimum
                  message: >-
                    A value of $10.00 buys 0.00011 BTC after rounding down to
                    BTC's 0.00001 size step, which is worth $9.29 at the price
                    limit of $84,430. The minimum is $10.00.
                  param: value
                  hint: Send a value of at least $10.14.
                  details:
                    value: '10.00'
                    value_after_rounding: '9.29'
                    min_value: '10.00'
                    smallest_passing_value: '10.14'
                  errors: []
                  retryable: false
                  doc_url: >-
                    https://docs.tradingapi.dev/api-reference/errors#order_below_minimum
    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
    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
    Unavailable:
      description: A service we depend on failed. Retry the same request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unavailable:
              value:
                error:
                  type: unavailable
                  code: unavailable
                  message: The exchange could not be reached.
                  param: null
                  hint: >-
                    Retry the same request with the same client_order_id; an
                    order may already have been recorded.
                  details: {}
                  errors: []
                  retryable: true
                  doc_url: https://docs.tradingapi.dev/api-reference/errors#unavailable
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: tapi_…
      description: >-
        An API key from the account page, sent as `Authorization: Bearer
        tapi_…`.

````