# Your execution quality

`GET https://app.skylit.ai/api/nexus/v1/journal/execution`

API: Nexus.

What your fills cost you against the quoted midpoint on one of your accounts: the spread you faced at each fill, how far from the mid you filled (positive is worse for you, on buys and sells alike), what that cost in dollars, and that cost as a share of what you won. Getting in and getting out are reported apart. Read only.

Only fills with a bid and ask recorded at fill time can be measured: the averages cover `fillsAnalyzed` of `fillsTotal`. With no measured fill, `avgSpreadWidth`, `avgSlippage` and `totalSlippageCost` are `null`, never `0`, and `buckets` is empty. `slippageShareOfGross` is `null` when nothing was won in the range (`grossProfit` 0). It has no upper limit: a small win beside a costly fill can be several hundred percent, so read it with `grossProfit`. The cost counts measured fills only while `grossProfit` counts every winning trade, so with `fillsAnalyzed` below `fillsTotal` the share reads low.

`range` is `7d`, `30d` (the default), `90d`, `ytd` or `all`. `account` is `main` (your simulated wallet) or `agent` (your bot's account); `port` is one of your ports. `meta` says which account and port were read.

```bash
curl -s "https://app.skylit.ai/api/nexus/v1/journal/execution?range=30d&account=agent" \
  -H "Authorization: Bearer $SKYLIT_API_KEY"
```

## Authentication

Send your Skylit API key as a bearer token: `Authorization: Bearer <key>`. No other header is accepted.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `range` | query | string | no |  (one of `7d`, `30d`, `90d`, `ytd`, `all`; default `30d`) |
| `account` | query | string | no | Which of your accounts. Left out, your default account. (one of `main`, `agent`) |
| `port` | query | string | no | One of your port ids (GET /v1/trading/ports). An account sent beside it must agree with it. |

## Example request

```bash
curl "https://app.skylit.ai/api/nexus/v1/journal/execution" \
  -H "Authorization: Bearer $SKYLIT_API_KEY"
```

## Responses

### 200

Your execution quality on that account.

One round trip, bought at the ask and sold at the bid, +17:

```json
{
  "data": {
    "range": "all",
    "fillsAnalyzed": 2,
    "fillsTotal": 2,
    "grossProfit": 17,
    "buckets": [
      {
        "key": "buy",
        "label": "Getting in",
        "fills": 1,
        "contracts": 1,
        "avgSpreadWidth": 0.04,
        "avgSlippage": 0.02,
        "slippageCost": 2
      },
      {
        "key": "sell",
        "label": "Getting out",
        "fills": 1,
        "contracts": 1,
        "avgSpreadWidth": 0.04,
        "avgSlippage": 0.02,
        "slippageCost": 2
      }
    ],
    "avgSpreadWidth": 0.04,
    "avgSlippage": 0.02,
    "totalSlippageCost": 4,
    "slippageShareOfGross": 23.52941176470588
  },
  "meta": {
    "account": "main",
    "port": null
  }
}
```

Two fills with no quote recorded:

```json
{
  "data": {
    "range": "all",
    "fillsAnalyzed": 0,
    "fillsTotal": 2,
    "grossProfit": 17,
    "buckets": [],
    "avgSpreadWidth": null,
    "avgSlippage": null,
    "totalSlippageCost": null,
    "slippageShareOfGross": null
  },
  "meta": {
    "account": "agent",
    "port": "7d1c0e7e-0000-4000-8000-000000000000"
  }
}
```

### 400

`bad_request`: range is not one of 7d, 30d, 90d, ytd, all; account is not main or agent, or it does not agree with the port.

### 401

Missing or invalid key.

### 404

`port_not_found`: that port is not one of yours. `user_not_found`: this account has not used Nexus yet.
