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

# GET /v1/fills — Query Subaccount Execution Fill Records

> Retrieve fill records for a subaccount, including instrument, price, quantity, and timestamp for each execution. Endpoint: GET /v1/fills.

A fill record is created each time one of your orders executes against the book, in whole or in part. Call `client.portfolio.fills()` to retrieve the complete fill history for a subaccount, giving you a granular audit trail of every execution including instrument, side, price, quantity, and timestamp. This data underpins your trade reconciliation, PnL attribution, and post-trade reporting workflows.

## Method

```
client.portfolio.fills(subaccount_id=None)
```

**Endpoint:** `GET /v1/fills`

## Example

```python theme={"dark"}
from molecule import Molecule

client = Molecule(
    base_url="https://api.molecule.trade",
    key_id="key_abc123",
    private_key="<base64-encoded-ed25519-seed>",
)

fills = client.portfolio.fills(subaccount_id="sa_abc123")

for fill in fills:
    print(fill["order_id"], fill["instrument_id"], fill["price"], fill["qty"])
```

## Parameters

<ParamField query="subaccount_id" type="string">
  The subaccount whose fill history to retrieve. Omit to retrieve fills across all subaccounts associated with your key.
</ParamField>

## Response

The endpoint returns a list of fill objects. Common fields:

<ResponseField name="id" type="string">
  Unique fill identifier.
</ResponseField>

<ResponseField name="order_id" type="string">
  The Molecule order ID that generated this fill.
</ResponseField>

<ResponseField name="instrument_id" type="integer">
  The venue-specific instrument that was executed.
</ResponseField>

<ResponseField name="side" type="&#x22;BUY&#x22; | &#x22;SELL&#x22;">
  Direction of the fill.
</ResponseField>

<ResponseField name="price" type="string">
  Execution price as a decimal string.
</ResponseField>

<ResponseField name="qty" type="string">
  Executed quantity as a decimal string.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of the fill event.
</ResponseField>

## Accessing fills via the orders namespace

<Note>
  The same `GET /v1/fills` endpoint is also accessible as `client.orders.fills(subaccount_id)`. Both methods call the same endpoint with the same parameters. Use whichever namespace fits your code organisation — `portfolio.fills` for post-trade analysis, `orders.fills` when working alongside order lifecycle methods.
</Note>

```python theme={"dark"}
# Equivalent to client.portfolio.fills(subaccount_id="sa_abc123")
fills = client.orders.fills(subaccount_id="sa_abc123")
```

## Real-time fills

<Tip>
  Subscribe to the `/v1/ws/fills` WebSocket stream to receive fill events as they occur, rather than polling this REST endpoint. See the [WebSocket overview](/api/websockets/overview) for connection details.
</Tip>


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