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.

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): 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.

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": "f31771445d4a4387b624db858593839a",
  "name": "Data Entry Clerk",
  "email": "entry@example.com",
  "role": "entry",
  "role_label": "User",
  "credits": 99,
  "unlimited": false,
  "active": true,
  "last_login_at": "2026-10-03T16:07:52.456943",
  "pricing": {
    "enabled": true,
    "credits_per_lookup": 1,
    "signup_credits": 100
  },
  "from": "2026-09-04",
  "to": "2026-10-03",
  "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": 21
  },
  "daily": [
    {
      "day": "2026-10-03",
      "lookups": 1,
      "credits_used": 1,
      "tokens": 0
    }
  ],
  "previous": {
    "from": "2026-08-05",
    "to": "2026-09-03",
    "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-03T16:07:52.489239",
      "kind": "usage",
      "kind_label": "Lookup",
      "amount": -1,
      "balance_after": 99,
      "lookup_id": "13725d9529b240e38985244bea377685",
      "note": "",
      "created_by_name": null
    },
    {
      "id": 2,
      "created_at": "2026-10-03T16:07:51.107109",
      "kind": "signup",
      "kind_label": "Initial credits",
      "amount": 100,
      "balance_after": 100,
      "lookup_id": null,
      "note": "",
      "created_by_name": null
    }
  ]
}

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.

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.

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-03T16:07:52.489239",
      "kind": "usage",
      "kind_label": "Lookup",
      "amount": -1,
      "balance_after": 99,
      "lookup_id": "13725d9529b240e38985244bea377685",
      "note": "",
      "created_by_name": null,
      "user_id": "f31771445d4a4387b624db858593839a",
      "user_name": "Data Entry Clerk",
      "user_email": "entry@example.com",
      "tokens": 0
    },
    {
      "id": 2,
      "created_at": "2026-10-03T16:07:51.107109",
      "kind": "signup",
      "kind_label": "Initial credits",
      "amount": 100,
      "balance_after": 100,
      "lookup_id": null,
      "note": "",
      "created_by_name": null,
      "user_id": "f31771445d4a4387b624db858593839a",
      "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
  }
}

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.

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-03.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-03.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-03.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-03.csv\"",
  "bytes": 260
}

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.

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