Skip to the content

You are reading the reference as of 2026-10-05. The API serves the latest version. Read this page for the latest version

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). 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), usage (the fee of a lookup) or trial_lapse (what was left of the sign-up credits, taken off when the free trial ended). The kind filter of the list and of the download takes the same four values
amount number Positive for a grant, negative for a fee or for a lapse. A grant that removes credits is negative too
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

A row of the kind trial_lapse is written once per account at most. It takes off what was left of the credits given at sign-up after the free trial of the account ended, or earlier when the account was put on a plan other than the trial. Its amount is negative, or zero when nothing was left. It is written when the account is first seen after the end of the trial, by a refusal or by a read of its own usage (GET /api/usage/me) or plan (GET /api/plans/me), not by a read of the ledger alone, so its created_at can be later than the end of the trial. Credits that an administrator granted are not taken off. This page has no example of such a row.

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, then trial, read_only and entitlements.

trial is the free trial of the account, or null when no trial with an end applies to it: an administrator account, and so a key as long as the account that created it is one, an account created before 6 October 2026 (UTC), an account on a plan other than the trial, and every account while the service has the trial switched off. Otherwise it is an object:

Field Type Meaning
days integer The length of the trial, in days
started_at string When the trial started: the time the account was created, with its offset from UTC
ends_at string When the trial ends, or ended, with its offset from UTC
ended boolean Whether the trial has ended

read_only is true once the trial has ended, and false in every other case. A read-only account can still read, and the operations that create a lookup or change something answer 402 with the code trial_ended (Errors). The two examples below are one account, in the middle of its trial and after it. Their dates are those of an example.

During the trial:

{
  "plan": null,
  "restricted": false,
  "trial": {
    "days": 14,
    "started_at": "2027-01-01T09:30:00+00:00",
    "ends_at": "2027-01-15T09:30:00+00:00",
    "ended": false
  },
  "read_only": 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
    }
  ]
}

After it:

{
  "plan": null,
  "restricted": false,
  "trial": {
    "days": 14,
    "started_at": "2027-01-01T09:30:00+00:00",
    "ends_at": "2027-01-15T09:30:00+00:00",
    "ended": true
  },
  "read_only": true,
  "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
    }
  ]
}

Both are shortened: entitlements lists 2 of 26 items. entitlements lists every feature and limit:

Field Type Meaning
key string The name used in a plan refusal (Errors): 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 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.

GET /api/usage/me
curl "https://htspilot.com/api/usage/me" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/usage/me",
    headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
    method="GET",
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))
const response = await fetch("https://htspilot.com/api/usage/me", {
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());
Response 200. Example for a member account. Credit figures and the pricing block are illustrative.
{
  "user_id": "964b0a9f9a244ea5a532634489e6d850",
  "name": "Data Entry Clerk",
  "email": "entry@example.com",
  "role": "entry",
  "role_label": "User",
  "credits": 99,
  "unlimited": false,
  "active": true,
  "last_login_at": "2026-10-04T20:23:39.142322",
  "pricing": {
    "enabled": true,
    "credits_per_lookup": 1,
    "signup_credits": 100
  },
  "from": "2026-09-06",
  "to": "2026-10-05",
  "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": 20
  },
  "daily": [
    {
      "day": "2026-10-04",
      "lookups": 1,
      "credits_used": 1,
      "tokens": 0
    }
  ],
  "previous": {
    "from": "2026-08-07",
    "to": "2026-09-05",
    "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-04T20:23:39.172171",
      "kind": "usage",
      "kind_label": "Lookup",
      "amount": -1,
      "balance_after": 99,
      "lookup_id": "e154b4b4842a437b8a2f5866a468e535",
      "note": "",
      "created_by_name": null
    },
    {
      "id": 2,
      "created_at": "2026-10-04T20:23:37.835627",
      "kind": "signup",
      "kind_label": "Initial credits",
      "amount": 100,
      "balance_after": 100,
      "lookup_id": null,
      "note": "",
      "created_by_name": null
    }
  ]
}

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, trial_lapse or null No Only the entries of one kind. signup: the credits an account is given at sign-up. grant: an adjustment by an administrator, above zero for credits given and below zero for credits removed. usage: the fee of a lookup. trial_lapse: what was left of the credits given at sign-up, taken off after the free trial of the account ended, or earlier when the account was put on a plan other than the trial. An account has at most one such entry; its amount is zero when nothing was left, and it is written when the account is next seen after the end of the trial, so its time can be later than that end.
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.

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

GET /api/usage/ledger
curl "https://htspilot.com/api/usage/ledger?page=1&page_size=25" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/usage/ledger?page=1&page_size=25",
    headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
    method="GET",
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))
const response = await fetch("https://htspilot.com/api/usage/ledger?page=1&page_size=25", {
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());
Response 200. Example for a member account. Credit figures and the pricing block are illustrative.
{
  "items": [
    {
      "id": 3,
      "created_at": "2026-10-04T20:23:39.172171",
      "kind": "usage",
      "kind_label": "Lookup",
      "amount": -1,
      "balance_after": 99,
      "lookup_id": "e154b4b4842a437b8a2f5866a468e535",
      "note": "",
      "created_by_name": null,
      "user_id": "964b0a9f9a244ea5a532634489e6d850",
      "user_name": "Data Entry Clerk",
      "user_email": "entry@example.com",
      "tokens": 0
    },
    {
      "id": 2,
      "created_at": "2026-10-04T20:23:37.835627",
      "kind": "signup",
      "kind_label": "Initial credits",
      "amount": 100,
      "balance_after": 100,
      "lookup_id": null,
      "note": "",
      "created_by_name": null,
      "user_id": "964b0a9f9a244ea5a532634489e6d850",
      "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
  }
}

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, trial_lapse or null No Only the entries of one kind. signup: the credits an account is given at sign-up. grant: an adjustment by an administrator, above zero for credits given and below zero for credits removed. usage: the fee of a lookup. trial_lapse: what was left of the credits given at sign-up, taken off after the free trial of the account ended, or earlier when the account was put on a plan other than the trial. An account has at most one such entry; its amount is zero when nothing was left, and it is written when the account is next seen after the end of the trial, so its time can be later than that end.

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.

GET /api/usage/ledger/export
curl "https://htspilot.com/api/usage/ledger/export" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
  -o "credit-ledger-2026-10-05.csv"
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/usage/ledger/export",
    headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
    method="GET",
)
with urllib.request.urlopen(request) as response, open("credit-ledger-2026-10-05.csv", "wb") as out:
    out.write(response.read())
import { writeFile } from "node:fs/promises";

const response = await fetch("https://htspilot.com/api/usage/ledger/export", {
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
await writeFile("credit-ledger-2026-10-05.csv", Buffer.from(await response.arrayBuffer()));
Response 200. Example for a member account. Credit figures and the pricing block are illustrative.
{
  "file": true,
  "content_type": "text/csv",
  "content_disposition": "attachment; filename=\"credit-ledger-2026-10-05.csv\"",
  "bytes": 260
}

Get the plan

GET /api/plans/me

Returns 200 with MyPlanOut.

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.

GET /api/plans/me
curl "https://htspilot.com/api/plans/me" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/plans/me",
    headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
    method="GET",
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))
const response = await fetch("https://htspilot.com/api/plans/me", {
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());
Response 200. Example for a member account. Credit figures and the pricing block are illustrative.
{
  "plan": null,
  "restricted": false,
  "trial": null,
  "read_only": 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
    }
  ]
}