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

# Usage

> The credit balance of the account, what was spent, the credit ledger, and what the plan of the account allows.

These operations show the credit balance, the history and the plan of an account
([Rate limits and quotas](/rate-limits.md#credits)). A key reads the usage of the account that created it.

The example answers of this page are those of a member account, and their `pricing` block and credit figures are
illustrative: they are not the settings of the service.

## The usage object

| Field | Type | Meaning |
| --- | --- | --- |
| `credits` | number | The balance |
| `unlimited` | boolean | The account is exempt from credits |
| `pricing` | object | `enabled`, `credits_per_lookup` and `signup_credits`. Illustrative in the examples |
| `from`, `to` | string | The period the figures cover. The last 30 days by default |
| `totals` | object | `lookups` and `credits_used` in the period |
| `daily` | array | The same per day |
| `previous` | object | The totals of the period before, for comparison |
| `by_kind`, `by_market`, `by_status` | object | Lookups of the period, split |
| `ledger` | object | Credits `added`, `removed` and `net` in the period, and the same per kind |
| `transactions` | array | The latest 50 ledger rows of the account |

## The ledger row

| Field | Type | Meaning |
| --- | --- | --- |
| `id` | integer | The id of the row |
| `created_at` | string | ISO 8601, UTC |
| `kind`, `kind_label` | string | `signup` (the first credits of an account), `grant` (credits added or adjusted) or `usage` (the fee of a lookup) |
| `amount` | number | Positive for a grant, negative for a fee |
| `balance_after` | number | The balance after this row |
| `lookup_id` | string or null | The lookup a fee belongs to |
| `note` | string | A note on a grant |
| `user_id`, `user_name`, `user_email` | string | The account |

## The plan object

`plan` is the plan of the account, or `null` for an account without one; an account without a plan is not
restricted. `restricted` is returned next to it. `entitlements` lists every feature
and limit:

| Field | Type | Meaning |
| --- | --- | --- |
| `key` | string | The name used in a plan refusal ([Errors](/errors.md#plan-refusals)): `feature.batch`, `batch_max_rows` and so on |
| `kind` | string | `feature` (on or off) or `limit` (a number) |
| `category`, `label`, `unit_label` | string | For display, in the language of the reader |
| `enabled` | boolean | For a feature |
| `value`, `unlimited` | integer, boolean | For a limit: the number, or `unlimited` set to `true` |

Not every entitlement is enforced on API calls; [Rate limits and quotas](/rate-limits.md#plan-limits) lists the
ones that are.

## Get usage

`GET /api/usage/me`

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `date_from` | string or null | No | - |
| `date_to` | string or null | No | - |

**Returns** `200` with a JSON object, as in the example.

**Errors**: `401` No valid API key was sent; `403` The role of the key, or the plan of the account, does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
curl "https://htspilot.com/api/usage/me" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200`. Example for a member account. Credit figures and the pricing block are illustrative.

```json
{
  "user_id": "4363f5a21c0c4faf929abadcb1f82806",
  "name": "Data Entry Clerk",
  "email": "entry@example.com",
  "role": "entry",
  "role_label": "User",
  "credits": 99,
  "unlimited": false,
  "active": true,
  "last_login_at": "2026-10-03T19:48:04.090553",
  "pricing": {
    "enabled": true,
    "credits_per_lookup": 1,
    "signup_credits": 100
  },
  "from": "2026-09-05",
  "to": "2026-10-04",
  "totals": {
    "lookups": 1,
    "credits_used": 1
  },
  "llm": {
    "llm_calls": 0,
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0,
    "charged_lookups": 1,
    "avg_processing_ms": 19
  },
  "daily": [
    {
      "day": "2026-10-03",
      "lookups": 1,
      "credits_used": 1,
      "tokens": 0
    }
  ],
  "previous": {
    "from": "2026-08-06",
    "to": "2026-09-04",
    "lookups": 0,
    "credits_used": 0,
    "total_tokens": 0
  },
  "by_kind": [
    {
      "key": "single",
      "lookups": 1,
      "credits_used": 1
    }
  ],
  "by_market": [
    {
      "key": "US",
      "lookups": 1,
      "credits_used": 1
    }
  ],
  "by_status": [
    {
      "key": "proposed",
      "lookups": 1,
      "credits_used": 1
    }
  ],
  "ledger": {
    "added": 100,
    "removed": 1,
    "net": 99,
    "by_kind": [
      {
        "kind": "signup",
        "kind_label": "Initial credits",
        "count": 1,
        "added": 100,
        "removed": 0
      },
      {
        "kind": "usage",
        "kind_label": "Lookup",
        "count": 1,
        "added": 0,
        "removed": 1
      }
    ]
  },
  "transactions": [
    {
      "id": 3,
      "created_at": "2026-10-03T19:48:04.121993",
      "kind": "usage",
      "kind_label": "Lookup",
      "amount": -1,
      "balance_after": 99,
      "lookup_id": "93ee3f02698847b2a32a74b60a5eead1",
      "note": "",
      "created_by_name": null
    },
    {
      "id": 2,
      "created_at": "2026-10-03T19:48:02.727052",
      "kind": "signup",
      "kind_label": "Initial credits",
      "amount": 100,
      "balance_after": 100,
      "lookup_id": null,
      "note": "",
      "created_by_name": null
    }
  ]
}
```

Try it: https://docs.htspilot.com/explorer/#/Usage/getMyUsage

## List the credit ledger

`GET /api/usage/ledger`

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `date_from` | string or null | No | - |
| `date_to` | string or null | No | - |
| `user_id` | string or null | No | Up to 32 characters |
| `kind` | one of: signup, grant, usage or null | No | - |
| `page` | integer | No | Minimum 1, default `1` |
| `page_size` | integer | No | Minimum 1, maximum 200, default `25` |

**Returns** `200` with a JSON object, as in the example.

**Errors**: `401` No valid API key was sent; `403` The role of the key, or the plan of the account, does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
curl "https://htspilot.com/api/usage/ledger?page=1&page_size=25" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200`. Example for a member account. Credit figures and the pricing block are illustrative.

```json
{
  "items": [
    {
      "id": 3,
      "created_at": "2026-10-03T19:48:04.121993",
      "kind": "usage",
      "kind_label": "Lookup",
      "amount": -1,
      "balance_after": 99,
      "lookup_id": "93ee3f02698847b2a32a74b60a5eead1",
      "note": "",
      "created_by_name": null,
      "user_id": "4363f5a21c0c4faf929abadcb1f82806",
      "user_name": "Data Entry Clerk",
      "user_email": "entry@example.com",
      "tokens": 0
    },
    {
      "id": 2,
      "created_at": "2026-10-03T19:48:02.727052",
      "kind": "signup",
      "kind_label": "Initial credits",
      "amount": 100,
      "balance_after": 100,
      "lookup_id": null,
      "note": "",
      "created_by_name": null,
      "user_id": "4363f5a21c0c4faf929abadcb1f82806",
      "user_name": "Data Entry Clerk",
      "user_email": "entry@example.com",
      "tokens": 0
    }
  ],
  "total": 2,
  "page": 1,
  "page_size": 25,
  "totals": {
    "added": 100,
    "removed": 1,
    "net": 99
  }
}
```

Try it: https://docs.htspilot.com/explorer/#/Usage/listLedger

A key with the `admin` role sees the rows of every account and can filter by `user_id`; other keys see their own.

## Download the ledger

`GET /api/usage/ledger/export`

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `date_from` | string or null | No | - |
| `date_to` | string or null | No | - |
| `user_id` | string or null | No | Up to 32 characters |
| `kind` | one of: signup, grant, usage or null | No | - |

**Returns** `200` with a file (`text/csv`).

**Errors**: `401` No valid API key was sent; `403` The role of the key, or the plan of the account, does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
curl "https://htspilot.com/api/usage/ledger/export" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
  -o "credit-ledger-2026-10-04.csv"
```

**Example response** `200`. Example for a member account. Credit figures and the pricing block are illustrative.

```json
{
  "file": true,
  "content_type": "text/csv",
  "content_disposition": "attachment; filename=\"credit-ledger-2026-10-04.csv\"",
  "bytes": 260
}
```

Try it: https://docs.htspilot.com/explorer/#/Usage/exportLedger

## Get the plan

`GET /api/plans/me`

**Returns** `200` with a JSON object, as in the example.

**Errors**: `401` No valid API key was sent; `403` The role of the key, or the plan of the account, does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
curl "https://htspilot.com/api/plans/me" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200`. Example for a member account. Credit figures and the pricing block are illustrative. (long lists and texts are cut)

```json
{
  "plan": null,
  "restricted": false,
  "entitlements": [
    {
      "key": "feature.market_us",
      "kind": "feature",
      "category": "markets",
      "label": "US market (HTS)",
      "unit_label": null,
      "enabled": true
    },
    {
      "key": "feature.market_eu",
      "kind": "feature",
      "category": "markets",
      "label": "EU market (CN and TARIC)",
      "unit_label": null,
      "enabled": true
    }
  ]
}
```

Try it: https://docs.htspilot.com/explorer/#/Usage/getMyPlan