Skip to the content

Batches

Classify a file of products - upload an .xlsx or .csv file, choose the columns, start it, follow its progress and download the results.

A batch classifies every row of a spreadsheet. The flow has five steps:

  1. Upload the file (POST /api/batches). The answer lists the columns found, a suggested mapping and a preview. Nothing is classified yet.
  2. Optionally check the rows with your column mapping (POST /api/batches/{batch_id}/validate).
  3. Start it (POST /api/batches/{batch_id}/start) with the column mapping. The start can answer 402 with one of three codes: out_of_credits when the account cannot be charged for the rows, trial_ended when the free trial of the account has ended, and owner_trial_ended when the batch belongs to another account whose trial has ended (A read-only account).
  4. Poll GET /api/batches/{batch_id}/progress until the status is completed or completed_with_errors, or wait for the batch.completed webhook (Asynchronous work).
  5. Read the rows (GET /api/batches/{batch_id}/rows) or download the results as Excel (GET /api/batches/{batch_id}/export).

Each row that is classified becomes a lookup of the kind batch (Lookups) and can be charged (Rate limits and quotas). Rows send no lookup.completed event: the batch sends batch.completed when it is done. Batches need the plan feature feature.batch, and the number of rows is limited by the plan (Rate limits and quotas).

The file

An .xlsx or .csv file whose first row holds the column names. GET /api/batches/template gives a file to start from, with the columns description, material, use, composition, origin, notes, sku and hts_code. Your own column names work too: the column mapping says which column holds which field. Only description is required.

The size of the file is limited, and the limits are read from GET /api/limits (System) rather than assumed: the service can be configured with other values.

Limit Field of GET /api/limits Default
The size of the file, and the text of all its cells together max_upload_mb 25 MB unless the service is configured otherwise
The rows of the file. The header row is not counted; a blank row between two rows with data is max_batch_rows 2000 unless the service is configured otherwise
The size of an .xlsx file once unpacked max_upload_unpacked_mb 50 MB
The columns that hold a value max_upload_columns 64
The text of one cell max_upload_cell_chars 10000 characters
The description of a row max_description_chars 2000 characters unless the service is configured otherwise

A file over one of the first five is refused at upload, whole: it is never cut short. A file that is too large is answered 413 or 422 (When an upload is refused); a file over any of the other limits, and a file whose cells hold more text together than the size limit, is answered 422. The text of the cells is counted in bytes (How the text of a file is counted), and the column names have a limit of their own (The column names). A row whose description is too long does not refuse the file: the row check reports it on that row. The plan of the account can allow fewer rows than the service does, and answers 403 with the code plan_limit (Errors).

Mapping field Column that holds
description The product description. Required
material, use, composition, origin, notes The same fields as on a lookup
sku Your SKU code. Needed for save_to_catalog
existing_code The code in use today. It is checked against the tariff schedule and compared with the suggestion

The text of all the cells of a file together, the header row included, is held to max_upload_mb. It is counted in the bytes the text takes in UTF-8, not in characters, and a quote ("), a backslash, a tab and a line break inside a cell are each counted twice. A file over that is answered 422 with the code validation_error and the detail "The text in the cells of the file, once read, is larger than the 25 MB a file may hold. Split the rows into smaller files." (English, with the number in force). A file that is itself too large to be read has its own detail, File exceeds the 25 MB limit (A file that is too large).

So a file that is under max_upload_mb can be refused for its text:

  • an .xlsx file is compressed, so its text can be much larger than the file;
  • a .csv file in a legacy single-byte encoding takes one byte for an accented letter, which takes two bytes in UTF-8. A .csv file is read as UTF-8 (with or without a byte order mark) when it is valid UTF-8, else as Windows-1258, else as Latin-1. A file in another encoding (Shift JIS, EUC-KR, UTF-16) is read, but its text comes out wrong: save it as UTF-8;
  • a file full of quotes, backslashes, tabs or line breaks is counted at twice their number.

The same file is refused again. Split it into several files, with fewer rows each.

The column names

A row is stored and returned with its column names, so the names count once for every row: the bytes of all the column names of row 1 together (counted as in How the text of a file is counted), multiplied by the number of rows after the header, may not exceed max_upload_mb. The rows are the ones max_batch_rows counts. A name that is repeated is stored with a number after it, and an empty name is replaced by a label made from its column letter; both count as they are stored.

A file over that is answered 422 with the code validation_error and the detail "The column names in row 1 are too long for a file of 2000 rows. Shorten them and send the file again." (English, with the number of rows of the file). At the defaults, 25 MB and 2000 rows, the names of row 1 may take a little over 13,000 bytes in all; that number is an example of the defaults and not a limit of its own. This limit is not a field of GET /api/limits: it follows from max_upload_mb and from the rows of the file. The same file is refused again: shorten the names, or send fewer rows in each file.

The text of a cell

The service cleans the text of each cell when it reads the file. Every control character other than a tab and a line feed (the codes U+0000 to U+001F and U+007F to U+009F) becomes a space, CR LF and a lone CR become a line feed, and the cell is trimmed. The marks that set the direction of text (U+061C, U+200E, U+200F, U+202A to U+202E and U+2066 to U+2069) and the byte order mark (U+FEFF) are removed, not replaced by a space: none of them shows, and each changes what the text is to a search and to the check for duplicates. So preview, the raw of a row (The row object) and the exported file can differ from the bytes of the file in exactly that way. Tabs and line feeds inside a cell are kept.

The batch object

Field Type Meaning
id string The id of the batch
created_at, updated_at string ISO 8601, UTC
filename string The name of the uploaded file
status string uploaded, queued, running, completed or completed_with_errors
columns array The column names found in the file
column_mapping object The mapping the batch was started with
market, dataset_version string The market and tariff version of the batch
tariff_language string The language of the tariff text the lookups of the batch are run with and its export is written in, en or ja (The tariff language of a batch). en until the batch is started, and for a batch stored before the field existed
validation object The suggested mapping and the result of the row check
total_rows, processed_rows, failed_rows integer Counters
counts object Rows per row status
error string or null Not set today: a failure belongs to a row, and a batch with failed rows ends as completed_with_errors
save_to_catalog boolean Whether rows are saved to the SKU catalog
preview array The first rows of the file: after an upload, and on GET /api/batches/{batch_id} with preview=true

The row object

Field Type Meaning
row_index integer The row number in the file. The first data row is 2
raw object The cells of the row, by column name
status string pending, processing, done, error, skipped or duplicate (the same product as an earlier row, named in duplicate_of, whose result it reuses)
issues array What the row check found
duplicate_of integer or null The row_index it duplicates
lookup_id string or null The lookup of the row
attempts integer How often it was tried
error string or null Why it failed
result_status, recommended_code, confidence - The outcome of the lookup
code_check object The check of the existing code, when a column was mapped to existing_code
final_code string or null The reviewer's code, once decided

When the free trial of the account has ended, the account is read-only: reading a batch, its rows and its results, and downloading them, still work. Uploading a file, checking the rows, starting a batch, retrying the failed rows and editing a row are answered 402 with the code trial_ended, before the fields of the request are checked and before the batch is looked up, so an unknown batch id is answered 402 too. No batch is created and nothing is changed (Errors).

A batch that exists runs for the account that owns it. Starting it, retrying it and editing one of its rows are also refused when the trial of the owner has ended and the caller is another account, a key with the reviewer or admin role: the answer is 402 with the code owner_trial_ended, which does not say when the trial ended. The owner is answered trial_ended, with the date.

A batch that is running when the trial of its owner ends is not stopped as a whole. The rows that were not processed yet end with the status error, and their error says that the row was not processed because the free trial of the account that owns the batch had ended. For the owner that text names the day the trial ended, for as long as the trial is ended; every other reader, in the list of rows and in the exported file, reads the text without the date. POST /api/batches/{batch_id}/retry is refused for as long as the account is read-only.

GET /api/batches/template

An .xlsx file with the columns description, material, use, composition, origin, notes, sku and hts_code, example rows and a guide sheet.

Returns 200 with a file (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet).

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/batches/template
curl "https://htspilot.com/api/batches/template" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
  -o "hts_lookup_template.xlsx"
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/batches/template",
    headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
    method="GET",
)
with urllib.request.urlopen(request) as response, open("hts_lookup_template.xlsx", "wb") as out:
    out.write(response.read())
import { writeFile } from "node:fs/promises";

const response = await fetch("https://htspilot.com/api/batches/template", {
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
await writeFile("hts_lookup_template.xlsx", Buffer.from(await response.arrayBuffer()));
Response 200
{
  "file": true,
  "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "content_disposition": "attachment; filename=\"hts_lookup_template.xlsx\"",
  "bytes": 11736
}

Upload a file

POST /api/batches

Changes data in your account when executed. Send the file as multipart/form-data in the field file. The first row holds the column names; GET /api/batches/template gives a file to start from. The answer lists the columns found, a suggested mapping and a preview; nothing is classified until the batch is started.

Request body (multipart/form-data)

Name Type Required Description
file file Yes -

Returns 200 with BatchOut.

Errors: 401 No valid API key was sent; 402 The free trial of the account has ended and the account is read-only: trial_ended; 403 The role of the key, the plan of the account, or the workspace of the request does not allow this call; 408 The body of the request did not arrive in time. The file was not read and the connection is closed; 413 The body is larger than the upload limit allows (max_upload_mb of GET /api/limits); 415 The body is not multipart/form-data; 422 The request is not valid; 429 The service is reading other files, or the same caller already has uploads waiting. The file was not read: send it again after the seconds in the Retry-After header; 500 An unexpected failure.

Try it in the explorer

curl -X POST https://htspilot.com/api/batches \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
  -F "file=@products.csv"

Give an upload a request timeout above 90 seconds plus the time your connection needs to send the file: when the service is busy reading other files, the answer can be held that long before it comes (An upload that waits). The wait starts only once the whole file has arrived, so a timeout that covers the whole request must also cover the sending.

Read the answer as it arrives. The service gives a reader a time to take the whole answer, counted from the start of the answer, its status line and headers included: the time its size takes at 64 KiB per second, never less than 10 seconds and never more than 60. The answer of this call is small, so a reader has about 10 seconds. After that the service sends no more and closes the connection, and the client sees a body shorter than the length it was told. The file was read by then and the batch may exist, so read GET /api/batches before you send the file again, as after any timeout or connection error.

POST /api/batches
curl -X POST "https://htspilot.com/api/batches" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
  -F "file=@products.csv"
import json
import os
import urllib.request

boundary = "hts-pilot-example"
data = b""
for field, name in [["file", "products.csv"]]:
    with open(name, "rb") as f:
        data += (f"--{boundary}\r\nContent-Disposition: form-data; name=\"{field}\"; filename=\"{name}\"\r\n"
                 "Content-Type: application/octet-stream\r\n\r\n").encode() + f.read() + b"\r\n"
data += f"--{boundary}--\r\n".encode()

request = urllib.request.Request(
    "https://htspilot.com/api/batches",
    data=data,
    headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"], "Content-Type": f"multipart/form-data; boundary={boundary}"},
    method="POST",
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))
import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("products.csv")]), "products.csv");

const response = await fetch("https://htspilot.com/api/batches", {
  method: "POST",
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
  body: form,
});
console.log(await response.json());
Response 200
{
  "id": "a53434b5303c426b870175ee20c46db0",
  "created_at": "2026-10-13T18:09:38.606296Z",
  "updated_at": "2026-10-13T18:09:38.607626Z",
  "filename": "products.csv",
  "status": "uploaded",
  "columns": [
    "description",
    "material"
  ],
  "column_mapping": {
    "description": "description",
    "material": "material",
    "origin": "origin",
    "sku": "sku",
    "existing_code": "hts_code"
  },
  "market": "",
  "dataset_version": null,
  "validation": {
    "suggested_mapping": {
      "description": "description",
      "material": "material",
      "origin": "origin",
      "sku": "sku",
      "existing_code": "hts_code"
    },
    "precheck": {
      "total": 3,
      "empty": 0,
      "examples": 0,
      "invalid": 0,
      "duplicates": 0,
      "valid": 3,
      "warnings": 0,
      "issues": []
    }
  },
  "total_rows": 3,
  "processed_rows": 0,
  "failed_rows": 0,
  "error": null,
  "save_to_catalog": false,
  "tariff_language": "en",
  "counts": {
    "pending": 3
  },
  "preview": [
    {
      "row_index": 2,
      "description": "Men's T-shirt, knitted, 100% cotton, short sleeves",
      "material": "cotton",
      "origin": "VN",
      "sku": "EXAMPLE-TSH-001",
      "hts_code": "6109.10.00.12"
    },
    {
      "row_index": 3,
      "description": "Cotton terry bath towel, 70 x 140 cm",
      "material": "cotton",
      "origin": "IN",
      "sku": "EXAMPLE-TWL-014",
      "hts_code": ""
    }
  ]
}

Besides the answers every operation has (Errors), an upload can be refused because the account is read-only, for its size, for how it is sent, because its body arrives too slowly, or because the service is busy. All these answers have the body of every other error: detail, in the language of the request, and code (Errors).

Status code Meaning What to do
401 unauthenticated The request names no key, or the key is not accepted (A request with no key). No batch was created Send a valid key in X-API-Key. Do not retry the same call
402 trial_ended The free trial of the account has ended and the account is read-only (A read-only account). No batch was created Do not retry: the same upload is refused again
408 request_timeout The file took too long to arrive and was not read (A file that arrives too slowly). No batch was created Do not retry on your own: a person or the calling program decides (a faster connection, a smaller file). Sending again is safe
413 payload_too_large The request is larger than the upload limit allows. No batch was created Do not send it again: the same file is refused again. Split the file
415 unsupported_media_type The body is not multipart/form-data (A body that is not a file). Nothing was read Fix how the request is built: a form with the field file. Do not retry
422 validation_error The file is over the size limit by only a little, or its text or its column names are too long, or it is over another limit, or it cannot be read (The file) Fix the file; the same file fails again
429 rate_limited The service is reading other files and had no room for yours, or the same account already has uploads waiting, or too many files are arriving at the moment (An upload that waits). Nothing was read and no batch was created Wait the seconds in Retry-After, then send the same upload again

The request is refused when its body is larger than max_upload_mb of GET /api/limits (megabytes of 1,048,576 bytes) plus 64 KiB, which is allowed for what a multipart body adds around the file. A length declared in Content-Length that is over this is refused before the body is parsed and before the key is checked, so such a 413 does not tell you whether the key is valid. A body sent without a declared length is counted as it arrives, and is refused with 413 when the count passes the limit; its key was checked before that. detail is File exceeds the 25 MB limit (English, with the number in force); the answer has no details.

A file that is over max_upload_mb by less than those 64 KiB passes that first check and is refused when the file is read, with 422 (validation_error) and the same detail. So a file over max_upload_mb is answered 413, or 422 in that narrow band: treat both as "the file is too large". The other limits of The file are answered 422 only.

What to do:

  • Read max_upload_mb from GET /api/limits before you send, and split a larger file into several.
  • Do not retry a 413.
  • A client that writes its whole body before it reads the answer (a browser, most HTTP libraries) can read the 413 when the whole body is at most 64 MiB, or twice the largest body the route lets through when that is more: the rest of the body is read and thrown away, the 413 is sent when the body has ended, and the connection stays usable. A larger body, or one still arriving 60 seconds after the refusal, gets the 413 at once with the header Connection: close, and a client that is still writing may see the connection reset instead of the answer. Treat a connection reset during the upload of a very large file as "probably too large": compare its size with max_upload_mb.
  • A client that sends Expect: 100-continue is answered at once, before it sends its body.

A request that names no credential at all, with no X-API-Key and no Authorization: Bearer ..., is answered 401 with the code unauthenticated before its body is read. In English the detail is "Please sign in". A key that is sent and not accepted is answered 401 in the same way, before its body is read and before any wait in line.

The checks made before the body is read come in this order: a declared Content-Length over the limit gives 413 first (so that 413 says nothing about the key), then a missing or not accepted credential gives 401, then a body that is not a form gives 415, then too many files arriving at the moment give 429 (An upload that waits). So for a caller that is not accepted, the 401 comes before the 415, and before the 408 and the 413 of a body that has no declared length. Like the 413, these answers are sent when the rest of the body has been read and thrown away, if it is small enough; otherwise the answer is sent at once with Connection: close, and a client that is still writing may see the connection closed instead of the answer.

Nothing was read and no batch was created. A 401 is a problem of configuration: do not retry it (Authentication).

A file is sent as multipart/form-data, in a form with the field file. A body whose Content-Type is anything else, or that has none, is answered 415 with the code unsupported_media_type before the body is read. In English the detail is "The file must be sent as multipart/form-data." The media type is read without its parameters and in any case.

This is a defect of the client: the same request is refused again. Fix how the request is built, and do not retry it. With curl, -F "file=@products.csv" builds the form and sets the Content-Type; let your HTTP client do the same instead of writing the header by hand.

A body under the size limit has a time to arrive in. The whole of it has the time the largest allowed body takes at 128 KiB per second (about 1 Mbit/s), and never less than 60 seconds: about 200 seconds at the default limit of 25 MB. That time follows the limit in force and not the size of the file you send. Between two pieces of the body there may be at most 30 seconds. Past either, the answer is 408 with the code request_timeout, and in English the detail is "The file took too long to arrive and was not read. Send it again."

The answer has the header Connection: close, and a client that is still writing may see the connection closed instead of the answer. The clock stops when the body has arrived: waiting in line (An upload that waits) and reading the file are not on it. Nothing was read and no batch was created.

What to do:

  • Do not retry a 408 automatically. The same file over the same connection is likely to be too slow again. A person, or the program that calls, decides: a faster connection, or a smaller file.
  • Sending the file again is safe: nothing was stored.

The service reads a limited number of uploaded files at the same time: 2 unless the service is configured otherwise. An upload that finds no room waits in line, first come first served, for up to 30 seconds (unless the service is configured otherwise, and never more than 90), and is then answered 429 with the code rate_limited, the header Retry-After: 10 and details.retry_after_seconds: 10. When the line is already full (four waiting for each place) the answer is the same and comes at once. In English the detail is "Other files are being read at the moment. Your file was not read; send it again in 10 seconds." The key is checked before the body is read and before the wait: a call with a key that is not accepted is answered 401.

The same answer is given before the file is read, when too many files are arriving at the moment. The service takes at most 16 upload bodies at the same time (unless it is configured otherwise), three of them from one caller. A body counts from the moment the service lets it through until its last byte has arrived; then the places above bound what is held. One more body is answered 429 with the same detail, Retry-After: 10 and details.retry_after_seconds: 10, and nothing of it is kept.

The places are shared between callers. A caller is an account: its API keys and its own sign-in sessions count together, so two keys of one account are one caller. One caller holds one place at a time and may have two more uploads waiting, and may have three bodies arriving at once; one upload more from the same caller is answered 429 at once, with Retry-After: 10 and details.retry_after_seconds: 10. In English its detail is "You already have 3 files being sent or waiting to be read. This file was not read; send it again in 10 seconds." An upload that waits for a place of its own caller does not keep another caller from a place that is free. A place is held until the answer of the upload has been read, not only until the file is parsed (Rate limits and quotas).

The file was not read and no batch was created, so sending the same upload again is safe and creates one batch. This is the one failure of an upload that is right to repeat on its own:

  • Send the uploads of one account one after the other, whatever keys they use. A 429 that comes at once means that the same caller already has uploads waiting or arriving, that the line is full, or that the service has as many files arriving as it takes.
  • Wait the seconds in Retry-After, send the same upload again, and stop after a bounded number of attempts.
  • Give the request a timeout above 90 seconds plus the time your connection needs to send the file, so that the answer is not lost to your own client.
  • After any other failure of an upload, above all a timeout or a connection error, do not send the file again blindly: the batch may exist. Read GET /api/batches first. An upload whose caller goes away while it waits in line is not read and not stored, but the client cannot know whether its file was still waiting or already read.

This is not a limit per minute: it does not count your calls, it only bounds how many files are read at once (Rate limits and quotas).

Check the rows

POST /api/batches/{batch_id}/validate

Changes data in your account when executed.

Path parameters

Name Type Description
batch_id string -

Request body (application/json)

Name Type Required Description
column_mapping ColumnMapping Yes -
market string No Up to 8 characters
tariff_version string or null No -
save_to_catalog boolean No Save/update the SKU in the shared catalog (requires a sku column). Default false
tariff_language string or null No Language of the tariff text: en (default) or ja. ja is offered for the market JP only, whose tariff Japan Customs publishes in an official Japanese edition and an official English edition, each a dataset of its own (language of a dataset): the call reads the dataset of that edition, and the lines of the result (description, full_description), the text given to the model, the official links and the evidence are then the Japanese edition's, and translations.en holds the English edition's text. The written reasons follow language. A market that offers en alone answers 422 to any other value; GET /api/datasets lists the languages of each market in tariff_languages. Without it: en. Up to 8 characters

column_mapping: ColumnMapping

Name Type Required Description
description string Yes -
material string or null No -
use string or null No -
composition string or null No -
origin string or null No -
notes string or null No -
sku string or null No -
existing_code string or null No Column with the HTS code currently in use: it is checked for validity and compared with the suggestion

Returns 200 with BatchOut.

Errors: 401 No valid API key was sent; 402 The free trial of the account has ended and the account is read-only: trial_ended; 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

POST /api/batches/{batch_id}/validate
curl -X POST "https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0/validate" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
  "column_mapping": {
    "description": "description",
    "material": "material",
    "origin": "origin",
    "sku": "sku",
    "existing_code": "hts_code"
  },
  "market": "US",
  "save_to_catalog": false
}'
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0/validate",
    data=json.dumps({
        "column_mapping": {
            "description": "description",
            "material": "material",
            "origin": "origin",
            "sku": "sku",
            "existing_code": "hts_code",
        },
        "market": "US",
        "save_to_catalog": False,
    }).encode(),
    headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"], "Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))
const response = await fetch("https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0/validate", {
  method: "POST",
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "column_mapping": {
      "description": "description",
      "material": "material",
      "origin": "origin",
      "sku": "sku",
      "existing_code": "hts_code"
    },
    "market": "US",
    "save_to_catalog": false
  }),
});
console.log(await response.json());
Response 200
{
  "id": "a53434b5303c426b870175ee20c46db0",
  "created_at": "2026-10-13T18:09:38.606296",
  "updated_at": "2026-10-13T18:09:38.607626",
  "filename": "products.csv",
  "status": "uploaded",
  "columns": [
    "description",
    "material"
  ],
  "column_mapping": {
    "description": "description",
    "material": "material",
    "origin": "origin",
    "sku": "sku",
    "existing_code": "hts_code"
  },
  "market": "",
  "dataset_version": null,
  "validation": {
    "suggested_mapping": {
      "description": "description",
      "material": "material",
      "origin": "origin",
      "sku": "sku",
      "existing_code": "hts_code"
    },
    "precheck": {
      "total": 3,
      "empty": 0,
      "examples": 0,
      "invalid": 0,
      "duplicates": 0,
      "valid": 3,
      "warnings": 0,
      "issues": []
    }
  },
  "total_rows": 3,
  "processed_rows": 0,
  "failed_rows": 0,
  "error": null,
  "save_to_catalog": false,
  "tariff_language": "en",
  "counts": {
    "pending": 3
  },
  "preview": [
    {
      "row_index": 2,
      "description": "Men's T-shirt, knitted, 100% cotton, short sleeves",
      "material": "cotton",
      "origin": "VN",
      "sku": "EXAMPLE-TSH-001",
      "hts_code": "6109.10.00.12"
    },
    {
      "row_index": 3,
      "description": "Cotton terry bath towel, 70 x 140 cm",
      "material": "cotton",
      "origin": "IN",
      "sku": "EXAMPLE-TWL-014",
      "hts_code": ""
    }
  ]
}

Start a batch

POST /api/batches/{batch_id}/start

Changes data in your account when executed. column_mapping names the column of the file for each field; only description is required. Spends credits for every row that is classified.

Path parameters

Name Type Description
batch_id string -

Request body (application/json)

Name Type Required Description
column_mapping ColumnMapping Yes -
market string No Up to 8 characters
tariff_version string or null No -
save_to_catalog boolean No Save/update the SKU in the shared catalog (requires a sku column). Default false
tariff_language string or null No Language of the tariff text: en (default) or ja. ja is offered for the market JP only, whose tariff Japan Customs publishes in an official Japanese edition and an official English edition, each a dataset of its own (language of a dataset): the call reads the dataset of that edition, and the lines of the result (description, full_description), the text given to the model, the official links and the evidence are then the Japanese edition's, and translations.en holds the English edition's text. The written reasons follow language. A market that offers en alone answers 422 to any other value; GET /api/datasets lists the languages of each market in tariff_languages. Without it: en. Up to 8 characters

column_mapping: ColumnMapping

Name Type Required Description
description string Yes -
material string or null No -
use string or null No -
composition string or null No -
origin string or null No -
notes string or null No -
sku string or null No -
existing_code string or null No Column with the HTS code currently in use: it is checked for validity and compared with the suggestion

Returns 200 with BatchOut.

Errors: 401 No valid API key was sent; 402 The free trial of the account has ended and the account is read-only: trial_ended. The batch belongs to another account, whose free trial has ended: owner_trial_ended. The credits of the account that is charged do not cover the lookups of the call: out_of_credits; 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 batch can be started once, from the status uploaded; a second start answers 409.

POST /api/batches/{batch_id}/start
curl -X POST "https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0/start" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
  "column_mapping": {
    "description": "description",
    "material": "material",
    "origin": "origin",
    "sku": "sku",
    "existing_code": "hts_code"
  },
  "market": "US",
  "save_to_catalog": false
}'
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0/start",
    data=json.dumps({
        "column_mapping": {
            "description": "description",
            "material": "material",
            "origin": "origin",
            "sku": "sku",
            "existing_code": "hts_code",
        },
        "market": "US",
        "save_to_catalog": False,
    }).encode(),
    headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"], "Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))
const response = await fetch("https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0/start", {
  method: "POST",
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "column_mapping": {
      "description": "description",
      "material": "material",
      "origin": "origin",
      "sku": "sku",
      "existing_code": "hts_code"
    },
    "market": "US",
    "save_to_catalog": false
  }),
});
console.log(await response.json());
Response 200
{
  "id": "a53434b5303c426b870175ee20c46db0",
  "created_at": "2026-10-13T18:09:38.606296",
  "updated_at": "2026-10-13T18:09:38.650691Z",
  "filename": "products.csv",
  "status": "queued",
  "columns": [
    "description",
    "material"
  ],
  "column_mapping": {
    "description": "description",
    "material": "material",
    "origin": "origin",
    "sku": "sku",
    "existing_code": "hts_code"
  },
  "market": "US",
  "dataset_version": "2026-SAMPLE",
  "validation": {
    "suggested_mapping": {
      "description": "description",
      "material": "material",
      "origin": "origin",
      "sku": "sku",
      "existing_code": "hts_code"
    },
    "precheck": {
      "total": 3,
      "empty": 0,
      "examples": 0,
      "invalid": 0,
      "duplicates": 0,
      "valid": 3,
      "warnings": 0,
      "issues": []
    },
    "final": {
      "total": 3,
      "empty": 0,
      "examples": 0,
      "invalid": 0,
      "duplicates": 0,
      "valid": 3,
      "warnings": 0,
      "issues": []
    },
    "lang": "en"
  },
  "total_rows": 3,
  "processed_rows": 0,
  "failed_rows": 0,
  "error": null,
  "save_to_catalog": false,
  "tariff_language": "en",
  "counts": {
    "pending": 3
  },
  "preview": []
}

The start body takes an optional tariff_language, en or ja, en when it is not sent. ja is offered for the market JP only (Tariff data): a start for another market that names it is answered 422 with the code validation_error, and the batch is not started. With ja the rows are run on the Japanese dataset of the version, and a start is answered 404 with not_found when that edition is not loaded (Errors).

The batch keeps the value, returned as tariff_language of the batch object. Every row is run as a lookup with that tariff language (Lookups), and the Excel export is written in it: with ja, the column of the line shows the text of the official Japanese edition and, below it, the text of the English edition. The reasons follow the language of the batch's lookups, and the labels of the file follow Accept-Language (Languages).

GET /api/batches/{batch_id}/progress

The status, the counters and version, a token that changes whenever the batch or its rows changed. Poll this and read the rows again only when version differs from the one last seen. The token is opaque: compare it, do not parse it.

Path parameters

Name Type Description
batch_id string -

Returns 200 with BatchProgressOut.

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/batches/{batch_id}/progress
curl "https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0/progress" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0/progress",
    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/batches/a53434b5303c426b870175ee20c46db0/progress", {
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());
Response 200
{
  "id": "a53434b5303c426b870175ee20c46db0",
  "status": "completed",
  "updated_at": "2026-10-13T18:09:38.945460",
  "total_rows": 3,
  "processed_rows": 3,
  "failed_rows": 0,
  "error": null,
  "counts": {
    "done": 3
  },
  "version": "68c030ef8b765475"
}

Get a batch

GET /api/batches/{batch_id}

Path parameters

Name Type Description
batch_id string -

Query parameters

Name Type Required Description
preview boolean No Default false

Returns 200 with BatchOut.

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/batches/{batch_id}
curl "https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0",
    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/batches/a53434b5303c426b870175ee20c46db0", {
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());
Response 200
{
  "id": "a53434b5303c426b870175ee20c46db0",
  "created_at": "2026-10-13T18:09:38.606296",
  "updated_at": "2026-10-13T18:09:38.607626",
  "filename": "products.csv",
  "status": "uploaded",
  "columns": [
    "description",
    "material"
  ],
  "column_mapping": {
    "description": "description",
    "material": "material",
    "origin": "origin",
    "sku": "sku",
    "existing_code": "hts_code"
  },
  "market": "",
  "dataset_version": null,
  "validation": {
    "suggested_mapping": {
      "description": "description",
      "material": "material",
      "origin": "origin",
      "sku": "sku",
      "existing_code": "hts_code"
    },
    "precheck": {
      "total": 3,
      "empty": 0,
      "examples": 0,
      "invalid": 0,
      "duplicates": 0,
      "valid": 3,
      "warnings": 0,
      "issues": []
    }
  },
  "total_rows": 3,
  "processed_rows": 0,
  "failed_rows": 0,
  "error": null,
  "save_to_catalog": false,
  "tariff_language": "en",
  "counts": {
    "pending": 3
  },
  "preview": []
}

List batches

GET /api/batches

Query parameters

Name Type Required Description
limit integer No Minimum 1, maximum 100, default 20

Returns 200 with BatchOut[].

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/batches
curl "https://htspilot.com/api/batches" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/batches",
    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/batches", {
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());
Response 200
[
  {
    "id": "a53434b5303c426b870175ee20c46db0",
    "created_at": "2026-10-13T18:09:38.606296",
    "updated_at": "2026-10-13T18:09:38.945460",
    "filename": "products.csv",
    "status": "completed",
    "columns": [
      "description",
      "material"
    ],
    "column_mapping": {
      "description": "description",
      "material": "material",
      "origin": "origin",
      "sku": "sku",
      "existing_code": "hts_code"
    },
    "market": "US",
    "dataset_version": "2026-SAMPLE",
    "validation": {
      "suggested_mapping": {
        "description": "description",
        "material": "material",
        "origin": "origin",
        "sku": "sku",
        "existing_code": "hts_code"
      },
      "precheck": {
        "total": 3,
        "empty": 0,
        "examples": 0,
        "invalid": 0,
        "duplicates": 0,
        "valid": 3,
        "warnings": 0,
        "issues": []
      },
      "final": {
        "total": 3,
        "empty": 0,
        "examples": 0,
        "invalid": 0,
        "duplicates": 0,
        "valid": 3,
        "warnings": 0,
        "issues": []
      },
      "lang": "en"
    },
    "total_rows": 3,
    "processed_rows": 3,
    "failed_rows": 0,
    "error": null,
    "save_to_catalog": false,
    "tariff_language": "en",
    "counts": {
      "done": 3
    },
    "preview": []
  }
]

List the rows

GET /api/batches/{batch_id}/rows

Path parameters

Name Type Description
batch_id string -

Query parameters

Name Type Required Description
status string or null No -
offset integer No Minimum 0, default 0
limit integer No Minimum 1, maximum 2000, default 200

Returns 200 with BatchRowOut[].

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/batches/{batch_id}/rows
curl "https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0/rows" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0/rows",
    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/batches/a53434b5303c426b870175ee20c46db0/rows", {
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());
Response 200
[
  {
    "row_index": 2,
    "raw": {
      "description": "Men's T-shirt, knitted, 100% cotton, short sleeves",
      "material": "cotton",
      "origin": "VN",
      "sku": "EXAMPLE-TSH-001",
      "hts_code": "6109.10.00.12"
    },
    "status": "done",
    "issues": [],
    "duplicate_of": null,
    "lookup_id": "c291b02c48da48959e49e71f1901b7dd",
    "attempts": 1,
    "error": null,
    "result_status": "proposed",
    "recommended_code": "6109.10.00.14",
    "confidence": 0.75,
    "code_check": {
      "status": "valid",
      "code": "6109.10.00.12",
      "description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets, tank tops and similar garments, knitted or crocheted > Of cotton > Men's or boys' > T-shirts, all white, short hemmed sleeves, hemmed bottom, crew or round neckline, or V-neck, without pockets, trim or embroidery",
      "detail": "Valid declarable code",
      "comparison": "same_hs6"
    },
    "final_code": null
  },
  {
    "row_index": 3,
    "raw": {
      "description": "Cotton terry bath towel, 70 x 140 cm",
      "material": "cotton",
      "origin": "IN",
      "sku": "EXAMPLE-TWL-014",
      "hts_code": ""
    },
    "status": "done",
    "issues": [],
    "duplicate_of": null,
    "lookup_id": "51fe75e5f485497980c3a980cef70f12",
    "attempts": 1,
    "error": null,
    "result_status": "proposed",
    "recommended_code": "6302.60.00.10",
    "confidence": 0.74,
    "code_check": {},
    "final_code": null
  }
]

Edit a row

PATCH /api/batches/{batch_id}/rows/{row_index}

Changes data in your account when executed. values maps column names of the file to their new text. row_index is the row number in the file (the first data row is 2).

Path parameters

Name Type Description
batch_id string -
row_index integer -

Request body (application/json)

Name Type Required Description
values object Yes -

Returns 200 with BatchOut.

Errors: 401 No valid API key was sent; 402 The free trial of the account has ended and the account is read-only: trial_ended. The batch belongs to another account, whose free trial has ended: owner_trial_ended; 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

PATCH /api/batches/{batch_id}/rows/{row_index}
curl -X PATCH "https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0/rows/2" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
  "values": {
    "description": "Men'\''s T-shirt, knitted, 100% cotton, short sleeves"
  }
}'
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0/rows/2",
    data=json.dumps({
        "values": {"description": "Men's T-shirt, knitted, 100% cotton, short sleeves"},
    }).encode(),
    headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"], "Content-Type": "application/json"},
    method="PATCH",
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))
const response = await fetch("https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0/rows/2", {
  method: "PATCH",
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "values": {
      "description": "Men's T-shirt, knitted, 100% cotton, short sleeves"
    }
  }),
});
console.log(await response.json());
Response 200
{
  "id": "a53434b5303c426b870175ee20c46db0",
  "created_at": "2026-10-13T18:09:38.606296",
  "updated_at": "2026-10-13T18:09:38.894080Z",
  "filename": "products.csv",
  "status": "queued",
  "columns": [
    "description",
    "material"
  ],
  "column_mapping": {
    "description": "description",
    "material": "material",
    "origin": "origin",
    "sku": "sku",
    "existing_code": "hts_code"
  },
  "market": "US",
  "dataset_version": "2026-SAMPLE",
  "validation": {
    "suggested_mapping": {
      "description": "description",
      "material": "material",
      "origin": "origin",
      "sku": "sku",
      "existing_code": "hts_code"
    },
    "precheck": {
      "total": 3,
      "empty": 0,
      "examples": 0,
      "invalid": 0,
      "duplicates": 0,
      "valid": 3,
      "warnings": 0,
      "issues": []
    },
    "final": {
      "total": 3,
      "empty": 0,
      "examples": 0,
      "invalid": 0,
      "duplicates": 0,
      "valid": 3,
      "warnings": 0,
      "issues": []
    },
    "lang": "en"
  },
  "total_rows": 3,
  "processed_rows": 3,
  "failed_rows": 0,
  "error": null,
  "save_to_catalog": false,
  "tariff_language": "en",
  "counts": {
    "done": 2,
    "pending": 1
  },
  "preview": []
}

POST /api/batches/{batch_id}/retry

Changes data in your account when executed.

Path parameters

Name Type Description
batch_id string -

Returns 200 with BatchOut.

Errors: 401 No valid API key was sent; 402 The free trial of the account has ended and the account is read-only: trial_ended. The batch belongs to another account, whose free trial has ended: owner_trial_ended; 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

POST /api/batches/{batch_id}/retry
curl -X POST "https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0/retry" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0/retry",
    headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
    method="POST",
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))
const response = await fetch("https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0/retry", {
  method: "POST",
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());
Response 200
{
  "id": "a53434b5303c426b870175ee20c46db0",
  "created_at": "2026-10-13T18:09:38.606296",
  "updated_at": "2026-10-13T18:09:38.945460",
  "filename": "products.csv",
  "status": "completed",
  "columns": [
    "description",
    "material"
  ],
  "column_mapping": {
    "description": "description",
    "material": "material",
    "origin": "origin",
    "sku": "sku",
    "existing_code": "hts_code"
  },
  "market": "US",
  "dataset_version": "2026-SAMPLE",
  "validation": {
    "suggested_mapping": {
      "description": "description",
      "material": "material",
      "origin": "origin",
      "sku": "sku",
      "existing_code": "hts_code"
    },
    "precheck": {
      "total": 3,
      "empty": 0,
      "examples": 0,
      "invalid": 0,
      "duplicates": 0,
      "valid": 3,
      "warnings": 0,
      "issues": []
    },
    "final": {
      "total": 3,
      "empty": 0,
      "examples": 0,
      "invalid": 0,
      "duplicates": 0,
      "valid": 3,
      "warnings": 0,
      "issues": []
    },
    "lang": "en",
    "retried_rows": 0
  },
  "total_rows": 3,
  "processed_rows": 3,
  "failed_rows": 0,
  "error": null,
  "save_to_catalog": false,
  "tariff_language": "en",
  "counts": {
    "done": 3
  },
  "preview": []
}

GET /api/batches/{batch_id}/export

Path parameters

Name Type Description
batch_id string -

Returns 200 with a file (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet).

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

The file is an Excel workbook in the language of the request (Languages).

GET /api/batches/{batch_id}/export
curl "https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0/export" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
  -o "products_hts_results.xlsx"
import json
import os
import urllib.request

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

const response = await fetch("https://htspilot.com/api/batches/a53434b5303c426b870175ee20c46db0/export", {
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
await writeFile("products_hts_results.xlsx", Buffer.from(await response.arrayBuffer()));
Response 200
{
  "file": true,
  "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "content_disposition": "attachment; filename=\"products_hts_results.xlsx\"",
  "bytes": 6841
}