# UN Comtrade Trade Data Scraper (`automation-lab/un-comtrade-trade-data-scraper`) Actor

Extract import/export trade rows from UN Comtrade by country, partner, HS code, flow, and period for sourcing and market analysis.

- **URL**: https://apify.com/automation-lab/un-comtrade-trade-data-scraper.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.02 / 1,000 item extracteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## UN Comtrade Trade Data Scraper

Extract import/export trade rows from the public UN Comtrade API by country, partner, HS commodity code, period, and flow. Use this actor to turn UN Comtrade JSON into a clean Apify dataset that is ready for spreadsheets, BI tools, procurement research, compliance monitoring, and market sizing.

### What does UN Comtrade Trade Data Scraper do?

UN Comtrade Trade Data Scraper collects structured international trade records from the public UN Comtrade API.

It helps you answer questions such as:

- 🌍 What did the United States import from the world in 2023?
- 🚢 Which HS commodity groups are growing for a reporter country?
- 📈 How do imports and exports compare across periods?
- 🧾 What CIF, FOB, quantity, and weight values are reported for a trade lane?
- 🔎 Which partner countries are relevant for a sourcing or market entry analysis?

The actor accepts UN reporter codes, partner codes, periods, HS commodity codes, and flow codes, then saves normalized rows to the default dataset.

### Who is it for?

This actor is built for analysts who need repeatable trade-data collection without writing API scripts.

- 📊 Trade analysts monitoring import/export flows
- 🛒 Procurement and sourcing teams comparing supplier countries
- 🏭 Manufacturers tracking commodity and component markets
- 🧭 Market researchers sizing cross-border demand
- 🛡️ Compliance and intelligence teams checking country exposure
- 💼 Consultants preparing trade lane or tariff impact reports
- 🧪 Data teams feeding warehouses, dashboards, or notebooks

### Why use this actor?

UN Comtrade is a valuable source, but raw API work can be repetitive. You need to know the endpoint, parameter names, country codes, HS codes, and response shape. This actor packages that into a reusable Apify workflow.

Benefits:

- ✅ Public HTTP/API source, no browser required
- ✅ Batches multiple countries, periods, commodities, and flows
- ✅ Normalizes values into typed dataset columns
- ✅ Includes source URL and timestamp for auditability
- ✅ Supports cheap smoke tests and larger analysis runs
- ✅ Ready for Apify integrations, webhooks, API clients, and MCP

### What data can it extract?

The actor saves one dataset row per UN Comtrade trade record.

| Field | Description |
| --- | --- |
| `period` | Requested period such as `2023` |
| `reporterCode` | UN numeric reporter code |
| `reporterISO` | Reporter ISO code when provided |
| `reporterName` | Reporter country or area name |
| `partnerCode` | UN numeric partner code |
| `partnerISO` | Partner ISO code when provided |
| `partnerName` | Partner country, area, or World |
| `flowCode` | Flow code such as `M` or `X` |
| `flowName` | Flow label such as Import or Export |
| `commodityCode` | HS commodity code |
| `commodityName` | Commodity description |
| `quantity` | Reported quantity |
| `quantityUnit` | Quantity unit abbreviation |
| `netWeightKg` | Net weight in kilograms when present |
| `grossWeightKg` | Gross weight in kilograms when present |
| `cifValueUsd` | CIF value in USD when present |
| `fobValueUsd` | FOB value in USD when present |
| `tradeValueUsd` | Primary trade value in USD |
| `sourceUrl` | API URL used for the record |
| `scrapedAt` | ISO timestamp for the actor run |

### How much does it cost to extract UN Comtrade trade data?

This actor uses pay-per-event pricing.

- A small start fee is charged once per run.
- A per-row event is charged for each trade row saved.
- You control cost with `maxRows`.
- Use small inputs first, then scale to more reporters, partners, periods, and HS codes.

The actor is designed as an HTTP/API scraper, so it does not use browsers or paid proxies by default.

### How to use it

1. Open the actor on Apify.
2. Enter one or more reporter country/area codes.
3. Enter partner codes. Use `0` for World.
4. Enter one or more periods.
5. Enter HS commodity codes such as `TOTAL`, `01`, `02`, or `8703`.
6. Choose flow codes such as `M` for imports and `X` for exports.
7. Set `maxRows` to cap output volume.
8. Run the actor.
9. Download the dataset as JSON, CSV, Excel, XML, or RSS.

### Input reference

#### Reporter country/area codes

Use UN Comtrade numeric reporter codes.

Examples:

- `842` — USA
- `156` — China
- `276` — Germany
- `392` — Japan
- `826` — United Kingdom

#### Partner country/area codes

Use UN Comtrade numeric partner codes. The default `0` means World.

#### Periods

For annual frequency, use years such as `2023` or `2022`.

For monthly frequency, use periods supported by the UN Comtrade API.

#### HS commodity codes

Use `TOTAL` for all commodities or HS chapters/headings such as:

- `01` — live animals
- `27` — mineral fuels
- `84` — machinery
- `85` — electrical machinery
- `8703` — motor cars

#### Flow codes

Common flow codes:

- `M` — imports
- `X` — exports

Advanced users can add other public API flow codes if supported by UN Comtrade.

#### Limits and delays

`maxRows` stops output after a specific number of rows. `requestDelayMillis` adds a delay between batched API calls to be polite to the public source.

### Example input

```json
{
  "reporterCodes": ["842", "156"],
  "partnerCodes": ["0"],
  "periods": ["2023", "2022"],
  "commodityCodes": ["TOTAL", "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24"],
  "flowCodes": ["M", "X"],
  "frequency": "A",
  "classification": "HS",
  "tradeType": "C",
  "includeDescriptions": true,
  "maxRows": 100,
  "requestDelayMillis": 250
}
````

### Example output

```json
{
  "period": "2023",
  "reporterName": "USA",
  "partnerName": "World",
  "flowName": "Import",
  "commodityCode": "TOTAL",
  "commodityName": "All Commodities",
  "tradeValueUsd": 3168471121076,
  "cifValueUsd": 3168471121076,
  "fobValueUsd": 3080052528515,
  "quantity": 0,
  "quantityUnit": "N/A",
  "sourceUrl": "https://comtradeapi.un.org/public/v1/preview/C/A/HS?...",
  "scrapedAt": "2026-06-30T00:00:00.000Z"
}
```

### Tips for better trade-data runs

- Start with `partnerCodes: ["0"]` for World totals.
- Use `TOTAL` before drilling down into HS chapters.
- Keep `maxRows` low while testing a new combination.
- Add more periods only after you confirm your reporter and commodity codes return data.
- Use imports and exports together for quick trade-balance checks.
- If a run returns no rows, verify the reporter, partner, period, HS code, and flow combination in UN Comtrade.

### Common workflows

#### Market sizing

Collect imports by HS code for a target reporter country and compare yearly values.

#### Sourcing analysis

Run a reporter country against multiple partner countries to identify supply concentration.

#### Export opportunity research

Compare export flows for competitor countries and commodity chapters.

#### Compliance monitoring

Track flows for sensitive commodities and countries over time.

#### Dashboard refreshes

Schedule the actor and send results to a warehouse or BI tool.

### Integrations

Apify datasets connect to many downstream workflows.

- Google Sheets for analyst review
- BigQuery or Snowflake for warehousing
- Make or Zapier for alerts
- Webhooks for run-complete automation
- Python notebooks for modelling
- BI tools for trend dashboards

### API usage: Node.js

```js
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/un-comtrade-trade-data-scraper').call({
  reporterCodes: ['842'],
  partnerCodes: ['0'],
  periods: ['2023'],
  commodityCodes: ['TOTAL', '84', '85'],
  flowCodes: ['M', 'X'],
  maxRows: 20,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### API usage: Python

```python
from apify_client import ApifyClient

client = ApifyClient('YOUR_APIFY_TOKEN')
run = client.actor('automation-lab/un-comtrade-trade-data-scraper').call(run_input={
    'reporterCodes': ['842'],
    'partnerCodes': ['0'],
    'periods': ['2023'],
    'commodityCodes': ['TOTAL', '84', '85'],
    'flowCodes': ['M', 'X'],
    'maxRows': 20,
})

items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)
```

### API usage: cURL

```bash
curl -X POST "https://api.apify.com/v2/acts/automation-lab~un-comtrade-trade-data-scraper/runs?token=$APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "reporterCodes": ["842"],
    "partnerCodes": ["0"],
    "periods": ["2023"],
    "commodityCodes": ["TOTAL", "84", "85"],
    "flowCodes": ["M", "X"],
    "maxRows": 20
  }'
```

### MCP: use with Claude and other AI tools

You can connect this actor through the Apify MCP server and ask AI tools to run trade-data tasks.

MCP URL:

`https://mcp.apify.com/?tools=automation-lab/un-comtrade-trade-data-scraper`

Claude Code setup:

```bash
claude mcp add apify-un-comtrade https://mcp.apify.com/?tools=automation-lab/un-comtrade-trade-data-scraper
```

Claude Desktop JSON config:

```json
{
  "mcpServers": {
    "apify-un-comtrade": {
      "url": "https://mcp.apify.com/?tools=automation-lab/un-comtrade-trade-data-scraper"
    }
  }
}
```

Example prompts:

- "Run UN Comtrade Trade Data Scraper for USA imports from World in 2023 for HS 84 and 85."
- "Compare China exports for TOTAL commodities in 2022 and 2023."
- "Fetch the first 100 UN Comtrade rows for USA and Germany imports by HS chapters."

### Scheduling

Use Apify schedules to refresh trade data weekly, monthly, or quarterly. Scheduled runs are useful for dashboards and recurring market reports.

### Webhooks

Use Apify webhooks to trigger a downstream workflow after each run. For example, send the dataset to a warehouse, Slack alert, or custom API endpoint.

### Data quality notes

UN Comtrade data availability depends on reporting countries, periods, commodities, and publication schedules. Some combinations return no rows. Some weight or quantity fields may be `null` or `N/A` depending on the reported data.

### Error handling

The actor retries transient API failures and rate-limit responses. If the public API returns an error field, the actor logs it. Enable `failOnApiError` if you want the run to stop on API error messages.

### Performance

The actor batches multiple values per request, which reduces API calls. It also supports a small delay between requests to avoid hammering the public service.

### Legality

This actor uses a public UN Comtrade API endpoint and stores factual trade records. You are responsible for using the data in compliance with UN Comtrade terms, Apify terms, and laws that apply to your project.

### FAQ

#### Why did I get zero rows?

The selected reporter, partner, period, commodity, and flow combination may not exist in the public dataset. Try `partnerCodes: ["0"]`, `commodityCodes: ["TOTAL"]`, and one recent annual period first.

#### What does partner code 0 mean?

Partner code `0` means World totals in UN Comtrade responses.

#### Can I use monthly data?

Yes. Set `frequency` to `M` and provide periods supported by the UN Comtrade monthly API.

#### Does this actor use proxies?

No. It calls a public HTTP API directly.

#### Can I request thousands of rows?

Yes, but start smaller. Increase `maxRows` after verifying your query produces the expected rows.

### Related scrapers

Explore other Automation Labs actors for market research and public data workflows:

- https://apify.com/automation-lab/google-search-results-scraper
- https://apify.com/automation-lab/website-contact-finder
- https://apify.com/automation-lab/rss-feed-scraper

### Changelog

- Initial version: public UN Comtrade API extraction for reporter, partner, period, HS commodity, and flow filters.

# Actor input Schema

## `reporterCodes` (type: `array`):

UN Comtrade numeric reporter codes. Example: 842 = USA, 156 = China, 276 = Germany, 392 = Japan.

## `partnerCodes` (type: `array`):

UN Comtrade numeric partner codes. Use 0 for World totals.

## `periods` (type: `array`):

Years for annual data (for example 2023) or monthly periods if using monthly frequency.

## `commodityCodes` (type: `array`):

HS commodity codes such as TOTAL, 01, 02, 84, 8703. Multiple codes are batched into API calls.

## `flowCodes` (type: `array`):

UN Comtrade flow codes. M = imports, X = exports. Advanced users can add re-import/re-export codes supported by the API.

## `frequency` (type: `string`):

A for annual data, M for monthly data.

## `classification` (type: `string`):

Classification search code. HS is the recommended default for Harmonized System commodity analysis.

## `tradeType` (type: `string`):

UN Comtrade trade type. C means commodities and is the default public trade data surface.

## `includeDescriptions` (type: `boolean`):

Request human-readable country, flow, commodity, customs, and transport descriptions from UN Comtrade.

## `maxRows` (type: `integer`):

Stop after this many dataset rows. Use a low value for smoke tests and higher values for analysis.

## `requestDelayMillis` (type: `integer`):

Small delay to be polite to the public UN Comtrade API when many batches are needed.

## `failOnApiError` (type: `boolean`):

When enabled, a UN Comtrade error field stops the run instead of logging a warning and saving matching rows.

## Actor input object example

```json
{
  "reporterCodes": [
    "842",
    "156"
  ],
  "partnerCodes": [
    "0"
  ],
  "periods": [
    "2023",
    "2022"
  ],
  "commodityCodes": [
    "TOTAL",
    "01",
    "02",
    "03",
    "04",
    "05",
    "06",
    "07",
    "08",
    "09",
    "10",
    "11",
    "12",
    "13",
    "14",
    "15",
    "16",
    "17",
    "18",
    "19",
    "20",
    "21",
    "22",
    "23",
    "24"
  ],
  "flowCodes": [
    "M",
    "X"
  ],
  "frequency": "A",
  "classification": "HS",
  "tradeType": "C",
  "includeDescriptions": true,
  "maxRows": 20,
  "requestDelayMillis": 250,
  "failOnApiError": false
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "reporterCodes": [
        "842",
        "156"
    ],
    "partnerCodes": [
        "0"
    ],
    "periods": [
        "2023",
        "2022"
    ],
    "commodityCodes": [
        "TOTAL",
        "01",
        "02",
        "03",
        "04",
        "05",
        "06",
        "07",
        "08",
        "09",
        "10",
        "11",
        "12",
        "13",
        "14",
        "15",
        "16",
        "17",
        "18",
        "19",
        "20",
        "21",
        "22",
        "23",
        "24"
    ],
    "flowCodes": [
        "M",
        "X"
    ],
    "frequency": "A",
    "classification": "HS",
    "tradeType": "C",
    "includeDescriptions": true,
    "maxRows": 20,
    "requestDelayMillis": 250,
    "failOnApiError": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/un-comtrade-trade-data-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "reporterCodes": [
        "842",
        "156",
    ],
    "partnerCodes": ["0"],
    "periods": [
        "2023",
        "2022",
    ],
    "commodityCodes": [
        "TOTAL",
        "01",
        "02",
        "03",
        "04",
        "05",
        "06",
        "07",
        "08",
        "09",
        "10",
        "11",
        "12",
        "13",
        "14",
        "15",
        "16",
        "17",
        "18",
        "19",
        "20",
        "21",
        "22",
        "23",
        "24",
    ],
    "flowCodes": [
        "M",
        "X",
    ],
    "frequency": "A",
    "classification": "HS",
    "tradeType": "C",
    "includeDescriptions": True,
    "maxRows": 20,
    "requestDelayMillis": 250,
    "failOnApiError": False,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/un-comtrade-trade-data-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "reporterCodes": [
    "842",
    "156"
  ],
  "partnerCodes": [
    "0"
  ],
  "periods": [
    "2023",
    "2022"
  ],
  "commodityCodes": [
    "TOTAL",
    "01",
    "02",
    "03",
    "04",
    "05",
    "06",
    "07",
    "08",
    "09",
    "10",
    "11",
    "12",
    "13",
    "14",
    "15",
    "16",
    "17",
    "18",
    "19",
    "20",
    "21",
    "22",
    "23",
    "24"
  ],
  "flowCodes": [
    "M",
    "X"
  ],
  "frequency": "A",
  "classification": "HS",
  "tradeType": "C",
  "includeDescriptions": true,
  "maxRows": 20,
  "requestDelayMillis": 250,
  "failOnApiError": false
}' |
apify call automation-lab/un-comtrade-trade-data-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=automation-lab/un-comtrade-trade-data-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "UN Comtrade Trade Data Scraper",
        "description": "Extract import/export trade rows from UN Comtrade by country, partner, HS code, flow, and period for sourcing and market analysis.",
        "version": "0.1",
        "x-build-id": "thxpvR5tZEqQhQoxx"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/automation-lab~un-comtrade-trade-data-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-automation-lab-un-comtrade-trade-data-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/automation-lab~un-comtrade-trade-data-scraper/runs": {
            "post": {
                "operationId": "runs-sync-automation-lab-un-comtrade-trade-data-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/automation-lab~un-comtrade-trade-data-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-automation-lab-un-comtrade-trade-data-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "reporterCodes",
                    "periods",
                    "commodityCodes",
                    "flowCodes"
                ],
                "properties": {
                    "reporterCodes": {
                        "title": "Reporter country/area codes",
                        "type": "array",
                        "description": "UN Comtrade numeric reporter codes. Example: 842 = USA, 156 = China, 276 = Germany, 392 = Japan.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "partnerCodes": {
                        "title": "Partner country/area codes",
                        "type": "array",
                        "description": "UN Comtrade numeric partner codes. Use 0 for World totals.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "periods": {
                        "title": "Periods",
                        "type": "array",
                        "description": "Years for annual data (for example 2023) or monthly periods if using monthly frequency.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "commodityCodes": {
                        "title": "HS commodity codes",
                        "type": "array",
                        "description": "HS commodity codes such as TOTAL, 01, 02, 84, 8703. Multiple codes are batched into API calls.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "flowCodes": {
                        "title": "Trade flow codes",
                        "type": "array",
                        "description": "UN Comtrade flow codes. M = imports, X = exports. Advanced users can add re-import/re-export codes supported by the API.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "frequency": {
                        "title": "Frequency",
                        "enum": [
                            "A",
                            "M"
                        ],
                        "type": "string",
                        "description": "A for annual data, M for monthly data.",
                        "default": "A"
                    },
                    "classification": {
                        "title": "Classification",
                        "type": "string",
                        "description": "Classification search code. HS is the recommended default for Harmonized System commodity analysis.",
                        "default": "HS"
                    },
                    "tradeType": {
                        "title": "Trade type",
                        "type": "string",
                        "description": "UN Comtrade trade type. C means commodities and is the default public trade data surface.",
                        "default": "C"
                    },
                    "includeDescriptions": {
                        "title": "Include descriptions",
                        "type": "boolean",
                        "description": "Request human-readable country, flow, commodity, customs, and transport descriptions from UN Comtrade.",
                        "default": true
                    },
                    "maxRows": {
                        "title": "Maximum rows",
                        "minimum": 1,
                        "maximum": 10000,
                        "type": "integer",
                        "description": "Stop after this many dataset rows. Use a low value for smoke tests and higher values for analysis.",
                        "default": 20
                    },
                    "requestDelayMillis": {
                        "title": "Delay between API calls (ms)",
                        "minimum": 0,
                        "maximum": 10000,
                        "type": "integer",
                        "description": "Small delay to be polite to the public UN Comtrade API when many batches are needed.",
                        "default": 250
                    },
                    "failOnApiError": {
                        "title": "Fail run on API error field",
                        "type": "boolean",
                        "description": "When enabled, a UN Comtrade error field stops the run instead of logging a warning and saving matching rows.",
                        "default": false
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
