> ## Documentation Index
> Fetch the complete documentation index at: https://traddal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Classify in bulk

> Classify up to 25 products in one request.

Requires the `classify:read` scope.

<ParamField body="items" type="array" required>
  1–25 items, each with the same shape as
  [Classify a product](/api-reference/classify/classify-product) (including
  an optional per-item `mode`).
</ParamField>

<ParamField body="mode" type="string">
  Classification mode applied to every item (an item's own `mode` wins).
</ParamField>

## Response

Each entry in `results` carries the full single-classify payload plus three
bulk conveniences: `hs_code` (the top code, or `null`), `confidence_score`
(the top score, or `null`), and `confidence` (the top confidence label, or
`"unclassifiable"`). An item that failed does not fail the batch — its entry
has `success: false` with a `reason`.

<ResponseField name="total" type="number">
  Number of items submitted.
</ResponseField>

<ResponseField name="processed" type="number">
  Number of items classified successfully.
</ResponseField>

<ResponseField name="results" type="array">
  One entry per item, in request order.
</ResponseField>

<ResponseField name="mode" type="string | null">
  The batch-level mode you sent, if any.
</ResponseField>

<ResponseField name="execution_time" type="number">
  Total processing time in milliseconds.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://{partner}.mytraddal.com/admin/api/v1/classify/bulk \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {access_token}' \
    -d '{
      "items": [
        { "description": "Nylon hiking backpack 40L", "destination_country": "US" },
        { "description": "Stainless steel water bottle 750ml", "destination_country": "US" }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "message": "",
    "total": 2,
    "processed": 2,
    "results": [
      {
        "success": true,
        "original_description": "Nylon hiking backpack 40L",
        "customs_description": "Backpack with outer surface of man-made textile materials",
        "usedWebSearch": false,
        "top_result": {
          "chapter": { "name": "Chapter", "number": "42", "description": "Articles of leather; travel goods, handbags and similar containers" },
          "heading": { "name": "Heading", "number": "4202", "description": "Trunks, suitcases, backpacks and similar containers" },
          "subheading": { "name": "Subheading", "number": "420292", "description": "With outer surface of sheeting of plastics or of textile materials" },
          "tariff": { "name": "Tariff", "number": "4202923120", "description": "Backpacks, of man-made fibers" },
          "confidence": "high",
          "score": 0.94
        },
        "results": [
          {
            "code": "4202923120",
            "country": "US",
            "chapter": { "name": "Chapter", "number": "42", "description": "Articles of leather; travel goods, handbags and similar containers" },
            "heading": { "name": "Heading", "number": "4202", "description": "Trunks, suitcases, backpacks and similar containers" },
            "subheading": { "name": "Subheading", "number": "420292", "description": "With outer surface of sheeting of plastics or of textile materials" },
            "tariff": { "name": "Tariff", "number": "4202923120", "description": "Backpacks, of man-made fibers" },
            "score": 0.94,
            "confidence": "high"
          }
        ],
        "country": "US",
        "mode": "pro",
        "data_source": { "version": "2026 Rev 7", "source": "hts_2026_rev7.csv", "imported_at": "2026-06-30T08:11:02.000Z" },
        "request_id": "0d4c7c58-2f5a-4a6f-9a41-b1f6f9f1d2aa",
        "hs_code": "4202923120",
        "confidence_score": 0.94,
        "confidence": "high"
      }
    ],
    "mode": null,
    "execution_time": 2381
  }
  ```
</ResponseExample>

<Note>
  For CSV files with thousands of rows, use the dashboard's bulk tools — uploads
  fan out to a queue and report progress live.
</Note>