# CBP Customs Rulings Search (CROSS) (`ryanclinton/cbp-customs-rulings`) Actor Search the CBP CROSS database for US Customs tariff classification rulings. Retrieve HTS codes, full ruling text, and ruling relationship chains from 220,000+ searchable rulings. - **URL**: https://apify.com/ryanclinton/cbp-customs-rulings.md - **Developed by:** [ryan clinton](https://apify.com/ryanclinton) (community) - **Categories:** Other, AI - **Stats:** 1 total users, 0 monthly users, 66.7% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing $20.00 / 1,000 result returneds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. 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 ## CBP Customs Rulings Search Search the U.S. Customs and Border Protection CROSS (Customs Rulings Online Search System) database for tariff classification rulings. Enter a product description or ruling number and get back structured ruling records with HTS tariff codes, ruling status, full ruling text, and ruling relationship chains showing revocations, modifications, and related decisions. CBP Customs Rulings Search queries the official rulings.cbp.gov API, which contains over 220,000 searchable rulings dating back decades. Results include the ruling number, subject line, HTS codes, commodity grouping, USMCA/NAFTA applicability, and the complete ruling text. The actor also tracks ruling status (active, revoked, or modified) and provides the full chain of related rulings so you can trace how a classification decision has evolved. ### What data can you extract? | Data Point | Source | Example | |------------|--------|---------| | **Ruling number** | CROSS database | `N082097` | | **Subject** | Ruling header | `Classification of electronic fitness trackers` | | **HTS tariff codes** | Tariff classification | `8517.62.0090` | | **Ruling date** | Filing metadata | `2023-06-15` | | **Ruling status** | Revocation/modification chain | `active`, `revoked`, `modified` | | **Collection** | Ruling office | `HQ` (Headquarters), `NY` (New York) | | **Commodity grouping** | Classification category | `Electronics` | | **USMCA/NAFTA flags** | Trade agreement applicability | `true` / `false` | | **Related rulings** | Cross-references | `N123456`, `H289712` | | **Full ruling text** | Complete legal text | Full classification analysis and decision | ### Why use CBP Customs Rulings Search? Researching customs classifications by hand on the CBP website means paginating through search results, opening each ruling individually, and manually tracking which rulings have been revoked or modified. For trade compliance professionals handling hundreds of product classifications, this process does not scale. This actor automates the entire workflow: search by keyword or ruling number, paginate through all results, fetch full ruling text, and output structured records with status tracking and relationship chains. **Built on the Apify platform**, CBP Customs Rulings Search gives you capabilities you won't get from a simple script: - **Scheduling** -- run daily or weekly to monitor new rulings in your product categories - **API access** -- trigger runs programmatically from Python, JavaScript, or any HTTP client - **Monitoring** -- get notified when runs fail or produce unexpected results - **Integrations** -- connect directly to Zapier, Make, Google Sheets, or webhooks ### Features - **Keyword search** across the full CROSS database with support for Boolean operators - **Direct ruling lookup** by ruling number for instant access to a specific decision - **Full ruling text retrieval** with concurrent batch fetching (5 at a time) and polite rate limiting - **Ruling status tracking** -- automatically determines whether each ruling is active, revoked, or modified based on the ruling relationship chain - **Ruling relationship chains** -- includes related rulings, modifications, revocations, and the rulings they revoke or modify - **Collection filtering** -- search across all rulings or limit to Headquarters (HQ) or New York (NY) collections - **Commodity group filtering** -- narrow results by category (Agriculture, Electronics, Automotive, Textiles, etc.) - **Date range filtering** -- restrict results to rulings issued within a specific time window - **HTS tariff code extraction** -- every ruling includes its associated HTS codes for direct use in import/export classification - **USMCA and NAFTA flags** -- identifies rulings relevant to North American trade agreements - **Pagination** -- automatically pages through large result sets up to your configured maximum ### Use cases for searching customs rulings #### Import/export compliance Customs brokers and trade compliance teams search for rulings on specific product types to determine the correct HTS classification before filing import declarations, reducing the risk of misclassification penalties. #### Product classification research Manufacturers launching new products research existing rulings for similar goods to predict how CBP will classify them and estimate duty rates before importing. #### Trade dispute preparation Legal teams compile ruling histories and revocation chains to build arguments for customs classification protests or petitions for new rulings. #### Tariff impact analysis Trade policy analysts search for all rulings within a commodity group to assess how many product categories are affected by proposed tariff changes. #### Compliance monitoring Companies set up scheduled runs to monitor new rulings in their product categories and get alerted when CBP issues a ruling that could affect their classifications. #### Academic and policy research Researchers analyze classification patterns across thousands of rulings to study trends in customs enforcement, trade policy, and tariff application. ### How to search customs rulings 1. **Enter a search term** -- Type a product description, commodity name, or HTS code in the search field. Boolean operators are supported for complex queries. 2. **Configure filters** -- Optionally narrow results by collection (HQ/NY), commodity group, or date range. Choose your preferred sort order. 3. **Run the actor** -- Click "Start" to begin the search. The actor will paginate through results and optionally fetch full ruling text for each match. 4. **Download results** -- Once finished, download your data as JSON, CSV, or Excel from the Dataset tab. Each row contains one complete ruling record. ### Input parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `searchTerm` | string | No* | -- | Keyword(s) to search for in rulings. Supports Boolean operators. | | `rulingNumber` | string | No* | -- | Look up a specific ruling by number (e.g., N082097, H289712). Overrides search if provided. | | `collection` | string | No | `ALL` | Filter by ruling office: `ALL`, `HQ` (Headquarters), or `NY` (New York). | | `commodityGrouping` | string | No | `ALL` | Filter by commodity category (e.g., Electronics, Agriculture, Automotive). | | `fromDate` | string | No | -- | Start date filter in YYYY-MM-DD format. | | `toDate` | string | No | -- | End date filter in YYYY-MM-DD format. | | `sortBy` | string | No | `RELEVANCE` | Sort order: `RELEVANCE`, `DATE_DESC` (newest first), or `DATE_ASC` (oldest first). | | `includeFullText` | boolean | No | `true` | Fetch the complete ruling text for each result. Slower but provides full ruling content. | | `maxResults` | integer | No | `50` | Maximum number of rulings to return (1-5,000). | *Either `searchTerm` or `rulingNumber` is required. #### Input examples **Search for electronics rulings:** ```json { "searchTerm": "electronics", "maxResults": 25 } ```` **Look up a specific ruling:** ```json { "rulingNumber": "N082097" } ``` **Search with filters and date range:** ```json { "searchTerm": "lithium battery", "collection": "HQ", "commodityGrouping": "Electronics", "fromDate": "2023-01-01", "toDate": "2024-12-31", "sortBy": "DATE_DESC", "maxResults": 100 } ``` **Quick search without full text (faster):** ```json { "searchTerm": "automotive sensors", "includeFullText": false, "maxResults": 200 } ``` #### Input tips - **Start without full text for large searches** -- Setting `includeFullText` to false skips individual ruling detail fetches, making searches with hundreds of results much faster. - **Use specific commodity groups** -- Filtering by commodity group reduces noise and returns more relevant results for your product category. - **Combine date filters with keywords** -- When monitoring for new rulings, use `fromDate` with `sortBy: DATE_DESC` to surface the most recent decisions first. ### Output example Each item in the output dataset represents one customs ruling: ```json { "rulingNumber": "N082097", "subject": "The tariff classification of electronic fitness trackers from China", "categories": ["Electrical Machinery", "Consumer Electronics"], "rulingDate": "2023-06-15", "collection": "NY", "htsTariffCodes": ["8517.62.0090"], "commodityGrouping": "Electronics", "status": "active", "isUsmca": false, "isNafta": false, "relatedRulings": ["N081234", "N083456"], "modifiedBy": [], "modifies": [], "revokedBy": [], "revokes": [], "fullText": "Dear Sir or Madam:\n\nIn your letter dated May 10, 2023...", "documentUrl": "https://rulings.cbp.gov/ruling/N082097.pdf", "sourceUrl": "https://rulings.cbp.gov/ruling/N082097" } ``` ### Output fields | Field | Type | Description | |-------|------|-------------| | `rulingNumber` | string | The unique ruling identifier (e.g., N082097, H289712) | | `subject` | string | Subject line describing the classification question | | `categories` | string\[] | Classification categories parsed from the ruling | | `rulingDate` | string | Date the ruling was issued (YYYY-MM-DD) | | `collection` | string | Ruling office: `HQ` (Headquarters) or `NY` (New York) | | `htsTariffCodes` | string\[] | Associated HTS tariff codes from the classification decision | | `commodityGrouping` | string | Commodity category (Electronics, Agriculture, etc.) or null | | `status` | string | Current ruling status: `active`, `revoked`, or `modified` | | `isUsmca` | boolean | Whether the ruling involves USMCA trade agreement provisions | | `isNafta` | boolean | Whether the ruling involves NAFTA trade agreement provisions | | `relatedRulings` | string\[] | Ruling numbers cross-referenced in this ruling | | `modifiedBy` | string\[] | Rulings that modify this ruling | | `modifies` | string\[] | Rulings that this ruling modifies | | `revokedBy` | string\[] | Rulings that revoke this ruling | | `revokes` | string\[] | Rulings that this ruling revokes | | `fullText` | string/null | Complete ruling text (null if `includeFullText` is false) | | `documentUrl` | string/null | URL to the ruling PDF document | | `sourceUrl` | string | Direct URL to the ruling on rulings.cbp.gov | ### How much does it cost to search customs rulings? CBP Customs Rulings Search uses compute-based pricing on the Apify platform. Costs depend on memory allocation (512 MB default) and run time. | Scenario | Results | Full Text | Est. Runtime | Est. Cost | |----------|---------|-----------|--------------|-----------| | Single ruling lookup | 1 | Yes | ~5 sec | ~$0.002 | | Small keyword search | 25 | Yes | ~30 sec | ~$0.01 | | Medium search | 100 | Yes | ~2 min | ~$0.03 | | Large search (no text) | 500 | No | ~1 min | ~$0.02 | | Large search (with text) | 500 | Yes | ~10 min | ~$0.10 | **Apify Free Tier:** New Apify accounts receive $5 of free platform credits each month, enough for hundreds of ruling searches. ### Search customs rulings using the API #### Python ```python from apify_client import ApifyClient client = ApifyClient("YOUR_API_TOKEN") run = client.actor("ryanclinton/cbp-customs-rulings").call(run_input={ "searchTerm": "lithium battery", "commodityGrouping": "Electronics", "sortBy": "DATE_DESC", "maxResults": 50, }) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(f"{item['rulingNumber']}: {item['subject']}") print(f" HTS: {', '.join(item['htsTariffCodes'])} | Status: {item['status']}") ``` #### JavaScript ```javascript import { ApifyClient } from "apify-client"; const client = new ApifyClient({ token: "YOUR_API_TOKEN" }); const run = await client.actor("ryanclinton/cbp-customs-rulings").call({ searchTerm: "lithium battery", commodityGrouping: "Electronics", sortBy: "DATE_DESC", maxResults: 50, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); for (const item of items) { console.log(`${item.rulingNumber}: ${item.subject}`); console.log(` HTS: ${item.htsTariffCodes.join(", ")} | Status: ${item.status}`); } ``` #### cURL ```bash ## Start the actor run curl -X POST "https://api.apify.com/v2/acts/ryanclinton~cbp-customs-rulings/runs?token=YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "searchTerm": "lithium battery", "commodityGrouping": "Electronics", "maxResults": 50 }' ## Fetch results (replace DATASET_ID from the run response) curl "https://api.apify.com/v2/datasets/DATASET_ID/items?token=YOUR_API_TOKEN&format=json" ``` ### How the CBP customs rulings search works The actor operates in two modes depending on the input: #### Mode 1: Direct ruling lookup When a `rulingNumber` is provided, the actor calls the CROSS API detail endpoint directly for that ruling number. The full ruling record -- including text, tariff codes, and relationship chains -- is returned as a single output record. #### Mode 2: Keyword search with pagination When a `searchTerm` is provided, the actor queries the CROSS search API with the specified filters. Results are paginated in batches of 100, with a polite 100ms delay between pages, until the `maxResults` limit or total hit count is reached. If `includeFullText` is enabled, the actor then enriches each search result by fetching the full ruling detail. This is done in concurrent batches of 5 requests with a 200ms delay between batches to respect the CROSS API's rate limits. Each ruling is then transformed into the clean output format: dates are normalized to YYYY-MM-DD, categories are parsed from the comma/semicolon-delimited string, HTS codes are extracted from the tariffs array, and the status is determined from the revocation and modification chains. #### Status determination logic - **Revoked**: The ruling has `operationallyRevoked` set to true, `isRevokedByOperationalLaw` is true, or the `revokedBy` array is non-empty. - **Modified**: The `modifiedBy` array is non-empty (and not revoked). - **Active**: Neither revoked nor modified. ### Commodity groups The CROSS database organizes rulings into these commodity groups for filtering: | Commodity Group | Example Products | |----------------|-----------------| | Agriculture and Prepared Products | Food, beverages, animal products, plant materials | | Apparel, Footwear and Textiles | Clothing, shoes, fabrics, textile articles | | Automotive and Aerospace | Vehicle parts, aircraft components, engines | | Base Metals | Steel, aluminum, copper, metal articles | | Consumer Products and Mass Merchandising | Household goods, toys, sporting goods | | Electronics | Computers, telecom equipment, consumer electronics | | Industrial and Manufacturing Materials | Chemicals, plastics, rubber, industrial equipment | | Machinery | Industrial machinery, mechanical appliances | | Petroleum, Natural Gas and Minerals | Fuels, mineral products, energy commodities | | Pharmaceuticals, Health and Chemicals | Drugs, medical devices, chemical compounds | ### Limitations - **CROSS API availability** -- The actor depends on the rulings.cbp.gov API. If the CROSS system is down for maintenance, searches will fail. - **Search syntax** -- The search term is passed directly to the CROSS API's search engine. Complex Boolean queries may behave differently than expected. - **Full text fetching is slow** -- Retrieving ruling text requires individual API calls per ruling (batched at 5 concurrent). Large searches with full text enabled can take several minutes. - **No full-text search within ruling bodies** -- The keyword search operates on the CROSS index, not the full ruling text. To search within ruling text, fetch results first, then filter locally. - **Historical coverage** -- While the database contains ~220,000 rulings dating back decades, older rulings may have incomplete metadata or missing text. - **Rate limiting** -- The actor uses polite delays (100-200ms between requests) to avoid overwhelming the CROSS API. This is not configurable. ### Integrations - [Zapier](https://apify.com/integrations/zapier) -- Trigger workflows when new rulings are found matching your search criteria. - [Make](https://apify.com/integrations/make) -- Build automated classification monitoring pipelines with 1,500+ app integrations. - [Google Sheets](https://apify.com/integrations/google-sheets) -- Export rulings directly to Google Sheets for team review and collaboration. - [Apify API](https://docs.apify.com/api/v2) -- Call the actor programmatically. Start runs, poll for completion, and download results in JSON, CSV, XML, or Excel. - [Webhooks](https://docs.apify.com/platform/integrations/webhooks) -- Get notified when a search run completes, then process results in your compliance system. ### FAQ **How many rulings are in the CROSS database?** The database contains approximately 220,000 searchable rulings. The actor reports the exact count from the API's statistics endpoint at the start of each search run. **Can I search by HTS code?** Yes. Enter the HTS code as your search term. The CROSS search engine indexes tariff codes, so queries like `8517.62` will return rulings classified under that heading. **What is the difference between HQ and NY collections?** HQ rulings are issued by CBP Headquarters in Washington, D.C. and typically address more complex or precedent-setting classification questions. NY rulings are issued by the National Commodity Specialist Division in New York and handle the majority of routine classification requests. **How do I know if a ruling is still valid?** Check the `status` field. Rulings with status `active` are still in effect. Rulings marked `revoked` have been superseded -- check the `revokedBy` array to find the replacement ruling. Rulings marked `modified` have been partially changed -- check `modifiedBy` for the modifying ruling. **Can I monitor for new rulings automatically?** Yes. Use [Apify Schedules](https://docs.apify.com/platform/schedules) to run the actor daily or weekly with `sortBy: DATE_DESC` and a `fromDate` filter set to your last check date. Combine with webhooks to get notified when new rulings appear. **What format are the ruling dates in?** All dates in the output are normalized to ISO YYYY-MM-DD format regardless of how they appear in the source data. **Is this the same data as on rulings.cbp.gov?** Yes. The actor queries the same internal JSON API that powers the rulings.cbp.gov website. The data is identical -- just structured for programmatic access. ### Related actors | Actor | How to combine | |-------|---------------| | [WHOIS Domain Lookup](https://apify.com/ryanclinton/whois-domain-lookup) | Research domain ownership for companies mentioned in customs rulings | | [Website Contact Scraper](https://apify.com/ryanclinton/website-contact-scraper) | Find contact information for customs brokers or importers referenced in rulings | | [B2B Lead Gen Suite](https://apify.com/ryanclinton/b2b-lead-gen-suite) | Build lead lists of companies in specific import/export categories identified through rulings research | ### Support Found a bug or have a feature request? Open an issue in the [Issues tab](https://console.apify.com/actors) on this actor's page. For custom compliance solutions or enterprise integrations, reach out through the Apify platform. # Actor input Schema ## `searchTerm` (type: `string`): Keyword(s) to search for in rulings. Supports Boolean operators. ## `rulingNumber` (type: `string`): Look up a specific ruling by number (e.g., N082097, H289712). Overrides search if provided. ## `collection` (type: `string`): Filter by ruling office ## `commodityGrouping` (type: `string`): Filter by commodity category ## `fromDate` (type: `string`): Start date filter (YYYY-MM-DD) ## `toDate` (type: `string`): End date filter (YYYY-MM-DD) ## `sortBy` (type: `string`): How to sort results ## `includeFullText` (type: `boolean`): Fetch the complete text for each ruling. Slower but provides full ruling content. ## `maxResults` (type: `integer`): Maximum number of rulings to return ## Actor input object example ```json { "searchTerm": "electronics", "collection": "ALL", "commodityGrouping": "ALL", "sortBy": "RELEVANCE", "includeFullText": true, "maxResults": 50 } ``` # Actor output Schema ## `results` (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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "searchTerm": "electronics" }; // Run the Actor and wait for it to finish const run = await client.actor("ryanclinton/cbp-customs-rulings").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "searchTerm": "electronics" } # Run the Actor and wait for it to finish run = client.actor("ryanclinton/cbp-customs-rulings").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 '{ "searchTerm": "electronics" }' | apify call ryanclinton/cbp-customs-rulings --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=ryanclinton/cbp-customs-rulings", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "CBP Customs Rulings Search (CROSS)", "description": "Search the CBP CROSS database for US Customs tariff classification rulings. Retrieve HTS codes, full ruling text, and ruling relationship chains from 220,000+ searchable rulings.", "version": "1.0", "x-build-id": "2cT9cim5RIbfmyacg" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ryanclinton~cbp-customs-rulings/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ryanclinton-cbp-customs-rulings", "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/ryanclinton~cbp-customs-rulings/runs": { "post": { "operationId": "runs-sync-ryanclinton-cbp-customs-rulings", "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/ryanclinton~cbp-customs-rulings/run-sync": { "post": { "operationId": "run-sync-ryanclinton-cbp-customs-rulings", "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", "properties": { "searchTerm": { "title": "Search Term", "type": "string", "description": "Keyword(s) to search for in rulings. Supports Boolean operators.", "default": "electronics" }, "rulingNumber": { "title": "Ruling Number (Direct Lookup)", "type": "string", "description": "Look up a specific ruling by number (e.g., N082097, H289712). Overrides search if provided." }, "collection": { "title": "Collection", "enum": [ "ALL", "HQ", "NY" ], "type": "string", "description": "Filter by ruling office", "default": "ALL" }, "commodityGrouping": { "title": "Commodity Group", "enum": [ "ALL", "Agriculture and Prepared Products", "Apparel, Footwear and Textiles", "Automotive and Aerospace", "Base Metals", "Consumer Products and Mass Merchandising", "Electronics", "Industrial and Manufacturing Materials", "Machinery", "Petroleum, Natural Gas and Minerals", "Pharmaceuticals, Health and Chemicals" ], "type": "string", "description": "Filter by commodity category", "default": "ALL" }, "fromDate": { "title": "From Date", "type": "string", "description": "Start date filter (YYYY-MM-DD)" }, "toDate": { "title": "To Date", "type": "string", "description": "End date filter (YYYY-MM-DD)" }, "sortBy": { "title": "Sort By", "enum": [ "RELEVANCE", "DATE_DESC", "DATE_ASC" ], "type": "string", "description": "How to sort results", "default": "RELEVANCE" }, "includeFullText": { "title": "Include Full Ruling Text", "type": "boolean", "description": "Fetch the complete text for each ruling. Slower but provides full ruling content.", "default": true }, "maxResults": { "title": "Max Results", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum number of rulings to return", "default": 50 } } }, "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 } } } } } } } } } } ```