Skip to the content

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.

The usage object

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

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. A row can have another kind, and a client must not fail on one it does not know: see below
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

Other kinds of row appear while a workspace has a paid plan, has bought a credit pack or has redeemed a voucher. plan_credits is the monthly credits of a paid plan. pack_credits is the credits of a one-off credit pack. plan_expired takes off what is left of those plan credits at the next monthly grant: plan credits do not roll over, and credits of every other kind do not expire this way. voucher is credits added by a redeemed credit code. These kinds are read in the list, the download and the ledger totals of GET /api/usage/me, but the kind filter does not take them yet.

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.

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. credits of GET /api/usage/me and of GET /api/auth/me is that balance; the other figures of GET /api/usage/me are still the caller's own lookups.
  • Where the caller's lookups are free, credits is null and unlimited is true.
  • GET /api/plans/me is the plan and the trial of the workspace. When the trial of a team workspace has ended, every member is answered 402 with trial_ended, and the date in it is the workspace's.
  • The ledger is the workspace's rows for its admin and owner, and one's own rows for everyone else. Ledger rows have organisation_id.

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, 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.

Try it in the explorer

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": "b967688667924ae7bef3d2736aa6380e",
  "name": "Data Entry Clerk",
  "email": "entry@example.com",
  "role": "entry",
  "role_label": "User",
  "credits": 99,
  "unlimited": false,
  "active": true,
  "last_login_at": "2026-10-13T18:09:39.176452",
  "pricing": {
    "enabled": true,
    "credits_per_lookup": 1,
    "signup_credits": 100
  },
  "from": "2026-09-15",
  "to": "2026-10-14",
  "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": 35
  },
  "daily": [
    {
      "day": "2026-10-13",
      "lookups": 1,
      "credits_used": 1,
      "tokens": 0
    }
  ],
  "previous": {
    "from": "2026-08-16",
    "to": "2026-09-14",
    "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-13T18:09:39.230354",
      "kind": "usage",
      "kind_label": "Lookup",
      "amount": -1,
      "balance_after": 99,
      "lookup_id": "ee4216190fd84ae080ef3bbad2263cab",
      "note": "",
      "created_by_name": null,
      "api_key_id": null
    },
    {
      "id": 2,
      "created_at": "2026-10-13T18:09:37.429349",
      "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.

Try it in the explorer

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.

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-13T18:09:39.230354",
      "kind": "usage",
      "kind_label": "Lookup",
      "amount": -1,
      "balance_after": 99,
      "lookup_id": "ee4216190fd84ae080ef3bbad2263cab",
      "note": "",
      "created_by_name": null,
      "api_key_id": null,
      "user_id": "b967688667924ae7bef3d2736aa6380e",
      "user_name": "Data Entry Clerk",
      "user_email": "entry@example.com",
      "tokens": 0
    },
    {
      "id": 2,
      "created_at": "2026-10-13T18:09:37.429349",
      "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": "b967688667924ae7bef3d2736aa6380e",
      "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.

Try it in the explorer

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-14.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-14.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-14.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-14.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, 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.

Try it in the explorer

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
    }
  ]
}