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. While the service has workspaces switched on, the balance and the plan are those of the key's workspace (Credits in a workspace).
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.
| Field | Type | Meaning |
|---|---|---|
credits |
number or null | The balance. null while workspaces are switched on and the caller's lookups in its workspace are free |
unlimited |
boolean | The account is exempt from credits, or its lookups in the workspace are free |
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, each with the fields of the ledger row below but user_id, user_name, user_email and tokens |
| 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 |
created_by_name |
string or null | The name of the administrator who made a grant, else null |
api_key_id |
string or null | The id of the API key the lookup was made with, on the row of its fee. null for a lookup made in the application and for every other row |
organisation_id |
string or null | While workspaces are switched on only: the workspace whose balance the row changed. null for a row from before workspaces. Absent otherwise |
user_id, user_name, user_email |
string | The account of the row. For a fee, the account that made the lookup, or the key it was made with |
tokens |
integer | Tokens of the classification engine used for the lookup of a fee, 0 otherwise |
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.
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.
While the service has workspaces switched on, credits, the plan and the free trial belong to the workspace a request acts in (Authentication):
- In a personal workspace the balance is the one of its account, as before.
- In a team workspace the lookups of every member, and of every key made there, are charged to one balance that
the team shares.
creditsofGET /api/usage/meand ofGET /api/auth/meis that balance; the other figures ofGET /api/usage/meare still the caller's own lookups. - Where the caller's lookups are free,
creditsisnullandunlimitedistrue. GET /api/plans/meis the plan and the trial of the workspace. When the trial of a team workspace has ended, every member is answered402withtrial_ended, and the date in it is the workspace's.- The ledger is the workspace's rows for its
adminandowner, and one's own rows for everyone else. Ledger rows haveorganisation_id.
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, the plan of the account, or the workspace of the request does not allow this call; 422 The request is not valid; 500 An unexpected failure.
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());200. Example for a member account. Credit figures and the pricing block are illustrative.{
"user_id": "822680e9bc5b4d7199ae7bd233271a97",
"name": "Data Entry Clerk",
"email": "entry@example.com",
"role": "entry",
"role_label": "User",
"credits": 99,
"unlimited": false,
"active": true,
"last_login_at": "2026-10-09T03:17:02.041562",
"pricing": {
"enabled": true,
"credits_per_lookup": 1,
"signup_credits": 100
},
"from": "2026-09-10",
"to": "2026-10-09",
"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": 39
},
"daily": [
{
"day": "2026-10-09",
"lookups": 1,
"credits_used": 1,
"tokens": 0
}
],
"previous": {
"from": "2026-08-11",
"to": "2026-09-09",
"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-09T03:17:02.100289",
"kind": "usage",
"kind_label": "Lookup",
"amount": -1,
"balance_after": 99,
"lookup_id": "0f000604f4234468b249a6cebaee93ff",
"note": "",
"created_by_name": null,
"api_key_id": null
},
{
"id": 2,
"created_at": "2026-10-09T03:16:59.981300",
"kind": "signup",
"kind_label": "Initial credits",
"amount": 100,
"balance_after": 100,
"lookup_id": null,
"note": "",
"created_by_name": null,
"api_key_id": 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, the plan of the account, or the workspace of the request 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.
While workspaces are switched on, an admin key sees the rows of its workspace, and a user_id that does not name
a member of it answers 404.
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());200. Example for a member account. Credit figures and the pricing block are illustrative.{
"items": [
{
"id": 3,
"created_at": "2026-10-09T03:17:02.100289",
"kind": "usage",
"kind_label": "Lookup",
"amount": -1,
"balance_after": 99,
"lookup_id": "0f000604f4234468b249a6cebaee93ff",
"note": "",
"created_by_name": null,
"api_key_id": null,
"user_id": "822680e9bc5b4d7199ae7bd233271a97",
"user_name": "Data Entry Clerk",
"user_email": "entry@example.com",
"tokens": 0
},
{
"id": 2,
"created_at": "2026-10-09T03:16:59.981300",
"kind": "signup",
"kind_label": "Initial credits",
"amount": 100,
"balance_after": 100,
"lookup_id": null,
"note": "",
"created_by_name": null,
"api_key_id": null,
"user_id": "822680e9bc5b4d7199ae7bd233271a97",
"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, the plan of the account, or the workspace of the request does not allow this call; 422 The request is not valid; 500 An unexpected failure.
curl "https://htspilot.com/api/usage/ledger/export" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
-o "credit-ledger-2026-10-09.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-09.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-09.csv", Buffer.from(await response.arrayBuffer()));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-09.csv\"",
"bytes": 260
}
GET /api/plans/me
Returns 200 with MyPlanOut.
Errors: 401 No valid API key was sent; 403 The role of the key, the plan of the account, or the workspace of the request does not allow this call; 422 The request is not valid; 500 An unexpected failure.
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());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
}
]
}