# TTB COLA Registry Scraper (`crawlerbros/ttb-cola-registry-scraper`) Actor

Scrape the US Treasury's TTB public COLA registry - approved beer, wine and spirits label applications. Search by brand/fanciful name, category, origin, permit, or date; fetch by TTB ID. Get applicant details, formulas, and label images.

- **URL**: https://apify.com/crawlerbros/ttb-cola-registry-scraper.md
- **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community)
- **Categories:** Automation, Developer tools, Integrations
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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

## TTB COLA Registry Scraper

Scrape the **TTB COLA Registry** — the US Treasury Department's Alcohol and Tobacco Tax and Trade Bureau (TTB) public database of Certificates of Label Approval (COLA) for beer, wine, and distilled spirits sold in the United States. Search by brand/fanciful name, beverage category, TTB class/type code, origin (US state or country), permit number, or date range — or fetch specific records directly by TTB ID. Every record includes the applicant's name and address, approval status, and the actual approved label image(s). HTTP-only against the public `ttbonline.gov` registry. No auth, no proxy, no login.

### What this actor does

- **Two modes:** `search` (query the registry) and `byTtbId` (direct lookup of known COLAs)
- **Rich filters:** product/brand name, beverage category, exact TTB class/type code, origin (233 US states + countries), permit number, vendor code, TTB ID range, serial number range, approval status, date-completed range
- **Applicant & compliance data:** approval status, formula, qualifications, applicant name/address, contact name/phone
- **Real label images:** the actual approved label artwork, re-hosted so it's accessible without a TTB session
- **Empty fields are omitted**

### Output per COLA record

- `ttbId` — 14-digit TTB identifier for the Certificate of Label Approval
- `permitId` — producer's plant registry / basic permit / brewer's number
- `serialNumber` — applicant's internal serial number for this application
- `dateCompleted`, `approvalDate`, `expirationDate`
- `status` — `APPROVED`, `DENIED`, or `SURRENDERED/REVOKED`
- `brandName`, `fancifulName`
- `classTypeCode`, `classTypeDescription` — TTB's beverage class/type (e.g. `141` / `BOURBON WHISKY`)
- `originCode`, `originDescription` — US state or country of origin
- `vendorCode`
- `typeOfApplication` — e.g. `LABEL APPROVAL`, `CERTIFICATE OF EXEMPTION`
- `forSaleIn`, `totalBottleCapacity`, `formula`
- `qualifications` — TTB's compliance notes on the approval
- `applicantName`, `applicantAddress`, `contactName`, `contactPhone`
- `labelImages[]` — `{ imageUrl, imageUrlOriginal, imageType }` for each approved label image (front, back, neck, keg collar, etc.)
- `sourceUrl` — the public COLA detail page on ttbonline.gov
- `recordType: "cola"`, `scrapedAt`

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `search` | `search` / `byTtbId` |
| `productOrFancifulName` | string | `whiskey` | Free-text match on brand/fanciful name (mode=search) |
| `productNameSearchType` | string | `E` | Match `productOrFancifulName` against brand only (`B`), fanciful only (`F`), or either (`E`) |
| `dateCompletedFrom` / `dateCompletedTo` | string | `01/01/2015` / `12/31/2024` | Date-completed range, MM/DD/YYYY, max 15-year span (required by TTB for any non-ID search) |
| `productCategory` | string | – | Curated beverage category (whisky, gin, vodka, rum, brandy, wine, beer, etc.) |
| `classTypeCode` | string | – | Exact 3-digit TTB class/type code; overrides `productCategory` |
| `originCode` | string | – | US state or country code |
| `permitId` | string | – | Producer's plant registry / basic permit number |
| `vendorCode` | string | – | TTB vendor code |
| `ttbIdFrom` / `ttbIdTo` | string | – | TTB ID range |
| `serialNumFrom` / `serialNumTo` | string | – | Applicant serial number range |
| `statusFilter` | string | – | Only emit `APPROVED` / `DENIED` / `SURRENDERED/REVOKED` |
| `ttbIds` | array | – | TTB IDs to fetch directly (mode=byTtbId) |
| `includeApplicantDetails` | bool | `true` | Fetch status, applicant, contact, formula, qualifications |
| `includeLabelImages` | bool | `true` | Fetch and re-host approved label images |
| `maxItems` | int | `20` | Hard cap (1–1000; TTB's own search window shows at most 1000 matches) |

#### Example: search by brand/fanciful name

```json
{
  "mode": "search",
  "productOrFancifulName": "bourbon",
  "dateCompletedFrom": "01/01/2023",
  "dateCompletedTo": "12/31/2024",
  "maxItems": 50
}
````

#### Example: browse a category by state of origin

```json
{
  "mode": "search",
  "productOrFancifulName": "",
  "productCategory": "WHISKY",
  "originCode": "13",
  "dateCompletedFrom": "01/01/2024",
  "dateCompletedTo": "12/31/2024",
  "maxItems": 100
}
```

#### Example: track a producer's approvals by permit number

```json
{
  "mode": "search",
  "productOrFancifulName": "",
  "permitId": "DSP-CO-20073",
  "dateCompletedFrom": "01/01/2020",
  "dateCompletedTo": "12/31/2024",
  "maxItems": 200
}
```

#### Example: direct lookup by TTB ID

```json
{
  "mode": "byTtbId",
  "ttbIds": ["24159001000118", "17009001000001"]
}
```

### Use cases

- **Label compliance teams** — check whether a competitor's or your own label has an active COLA before shipping
- **Competitive intelligence** — monitor new label approvals from a specific producer or permit number
- **New-product tracking** — spot new SKUs (fanciful names, flavors, formats) as soon as they're approved
- **Market research** — analyze approval volume by beverage category, state, or country of origin over time
- **Import/export due diligence** — verify a foreign producer's US label approval status and formula
- **Distributor onboarding** — pull applicant name, address, and permit details for a new supplier

### FAQ

**What is the TTB COLA Registry?** It's the US Alcohol and Tobacco Tax and Trade Bureau's public database of Certificates of Label Approval (COLA) — the federal approval required before a beer, wine, or spirits label can be sold in the United States. It's a public, no-login registry at [ttbonline.gov](https://ttbonline.gov/colasonline).

**Is this actor affiliated with TTB?** No — this is an independent, third-party actor built on TTB's public search interface. It is not affiliated with or endorsed by the Alcohol and Tobacco Tax and Trade Bureau.

**Why does my search need a date range?** TTB's own search form requires a "Date Completed" range for every query except a direct TTB ID lookup, and rejects any span longer than 15 years. The actor validates and auto-clamps oversized ranges so your run doesn't fail.

**What's the difference between `productCategory` and `classTypeCode`?** `productCategory` is a curated shortcut (e.g. `WHISKY`) mapped to the right TTB class/type code range. `classTypeCode` is the exact 3-digit TTB code (e.g. `141` = Bourbon Whisky) for users who need a single, precise category. Setting `classTypeCode` overrides `productCategory`.

**How many results can one search return?** TTB's own results window shows at most 1000 matching records per query (paginated 20 at a time), even if more technically match. Narrow your date range, category, or origin to stay under that cap.

**Why are some `labelImages` missing for a record?** Not every COLA has an image on file (e.g. some administrative or older filings), and a small number of image fetches can fail transiently. Missing images are simply omitted rather than emitting broken URLs.

**How fresh is the data?** TTB updates the registry as label applications are processed — typically within days of a decision. The actor always queries live.

**Can I fetch applicant/contact details without label images (or vice versa)?** Yes — `includeApplicantDetails` and `includeLabelImages` are independent toggles. Turning either off skips its extra request per record, which speeds up large runs.

# Actor input Schema

## `mode` (type: `string`):

What to fetch.

## `productOrFancifulName` (type: `string`):

Free-text match against the label's brand name and/or fanciful name. Substring matching is automatic (no need to add % wildcards yourself).

## `productNameSearchType` (type: `string`):

Which name field `productOrFancifulName` should match.

## `dateCompletedFrom` (type: `string`):

Start of the COLA completion-date range. TTB requires a date range for every search except a direct TTB ID lookup, and rejects any span greater than 15 years.

## `dateCompletedTo` (type: `string`):

End of the COLA completion-date range (<= 15 years after `dateCompletedFrom`).

## `productCategory` (type: `string`):

Curated beverage category, mapped internally to the matching TTB class/type code range. Leave blank for any category, or use `classTypeCode` below for an exact 3-digit TTB code.

## `classTypeCode` (type: `string`):

Exact 3-digit TTB class/type code (e.g. `101` = Straight Bourbon Whisky). Overrides `productCategory` when set. Full code list: ttbonline.gov COLAs Online > Advanced Search > Lookup Class Type.

## `originCode` (type: `string`):

Restrict results to labels originating from a specific US state or country.

## `permitId` (type: `string`):

Restrict results to a specific producer's permit/plant number (e.g. `DSP-CO-20073`).

## `vendorCode` (type: `string`):

Restrict results to a specific TTB vendor code.

## `ttbIdFrom` (type: `string`):

Lower bound of a TTB ID range (14-digit COLA identifier).

## `ttbIdTo` (type: `string`):

Upper bound of a TTB ID range.

## `serialNumFrom` (type: `string`):

Lower bound of the applicant's internal serial-number range.

## `serialNumTo` (type: `string`):

Upper bound of the applicant's internal serial-number range.

## `statusFilter` (type: `string`):

Only emit COLAs with this status (client-side filter, applied after fetching detail data).

## `ttbIds` (type: `array`):

One or more 14-digit TTB IDs to fetch directly, e.g. `24159001000118`.

## `includeApplicantDetails` (type: `boolean`):

Fetch each COLA's detail page for status, applicant name/address, contact info, formula, and qualifications. Adds one extra request per record.

## `includeLabelImages` (type: `boolean`):

Fetch each COLA's approved label image(s) and re-host them in this run's key-value store. Adds one extra request per record plus one per image.

## `maxItems` (type: `integer`):

Hard cap on emitted records. TTB's own search results window shows at most 1000 matches per query.

## Actor input object example

```json
{
  "mode": "search",
  "productOrFancifulName": "whiskey",
  "productNameSearchType": "E",
  "dateCompletedFrom": "01/01/2015",
  "dateCompletedTo": "12/31/2024",
  "productCategory": "",
  "originCode": "",
  "statusFilter": "",
  "ttbIds": [],
  "includeApplicantDetails": true,
  "includeLabelImages": true,
  "maxItems": 20
}
```

# Actor output Schema

## `colas` (type: `string`):

Dataset containing all scraped Certificate of Label Approval (COLA) records.

# 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 = {
    "mode": "search",
    "productOrFancifulName": "whiskey",
    "productNameSearchType": "E",
    "dateCompletedFrom": "01/01/2015",
    "dateCompletedTo": "12/31/2024",
    "productCategory": "",
    "originCode": "",
    "statusFilter": "",
    "ttbIds": [],
    "includeApplicantDetails": true,
    "includeLabelImages": true,
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawlerbros/ttb-cola-registry-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 = {
    "mode": "search",
    "productOrFancifulName": "whiskey",
    "productNameSearchType": "E",
    "dateCompletedFrom": "01/01/2015",
    "dateCompletedTo": "12/31/2024",
    "productCategory": "",
    "originCode": "",
    "statusFilter": "",
    "ttbIds": [],
    "includeApplicantDetails": True,
    "includeLabelImages": True,
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("crawlerbros/ttb-cola-registry-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 '{
  "mode": "search",
  "productOrFancifulName": "whiskey",
  "productNameSearchType": "E",
  "dateCompletedFrom": "01/01/2015",
  "dateCompletedTo": "12/31/2024",
  "productCategory": "",
  "originCode": "",
  "statusFilter": "",
  "ttbIds": [],
  "includeApplicantDetails": true,
  "includeLabelImages": true,
  "maxItems": 20
}' |
apify call crawlerbros/ttb-cola-registry-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=crawlerbros/ttb-cola-registry-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "TTB COLA Registry Scraper",
        "description": "Scrape the US Treasury's TTB public COLA registry - approved beer, wine and spirits label applications. Search by brand/fanciful name, category, origin, permit, or date; fetch by TTB ID. Get applicant details, formulas, and label images.",
        "version": "1.0",
        "x-build-id": "sagRbByp6UfbGQEmi"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/crawlerbros~ttb-cola-registry-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-crawlerbros-ttb-cola-registry-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/crawlerbros~ttb-cola-registry-scraper/runs": {
            "post": {
                "operationId": "runs-sync-crawlerbros-ttb-cola-registry-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/crawlerbros~ttb-cola-registry-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-crawlerbros-ttb-cola-registry-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": [
                    "mode"
                ],
                "properties": {
                    "mode": {
                        "title": "Mode",
                        "enum": [
                            "search",
                            "byTtbId"
                        ],
                        "type": "string",
                        "description": "What to fetch.",
                        "default": "search"
                    },
                    "productOrFancifulName": {
                        "title": "Product / brand / fanciful name (mode=search)",
                        "type": "string",
                        "description": "Free-text match against the label's brand name and/or fanciful name. Substring matching is automatic (no need to add % wildcards yourself).",
                        "default": "whiskey"
                    },
                    "productNameSearchType": {
                        "title": "Match name against",
                        "enum": [
                            "E",
                            "B",
                            "F"
                        ],
                        "type": "string",
                        "description": "Which name field `productOrFancifulName` should match.",
                        "default": "E"
                    },
                    "dateCompletedFrom": {
                        "title": "Date completed — from (MM/DD/YYYY)",
                        "type": "string",
                        "description": "Start of the COLA completion-date range. TTB requires a date range for every search except a direct TTB ID lookup, and rejects any span greater than 15 years.",
                        "default": "01/01/2015"
                    },
                    "dateCompletedTo": {
                        "title": "Date completed — to (MM/DD/YYYY)",
                        "type": "string",
                        "description": "End of the COLA completion-date range (<= 15 years after `dateCompletedFrom`).",
                        "default": "12/31/2024"
                    },
                    "productCategory": {
                        "title": "Product category",
                        "enum": [
                            "",
                            "WINE",
                            "WHISKY",
                            "GIN",
                            "VODKA",
                            "RUM",
                            "BRANDY",
                            "CORDIALS_AND_LIQUEURS",
                            "COCKTAILS_AND_MIXED_DRINKS",
                            "MALT_BEVERAGES_DOMESTIC",
                            "MALT_BEVERAGES_IMPORTED",
                            "OTHER_SPIRITS_DOMESTIC",
                            "TEQUILA_MEZCAL_AND_OTHER_IMPORTED_SPIRITS"
                        ],
                        "type": "string",
                        "description": "Curated beverage category, mapped internally to the matching TTB class/type code range. Leave blank for any category, or use `classTypeCode` below for an exact 3-digit TTB code.",
                        "default": ""
                    },
                    "classTypeCode": {
                        "title": "Exact TTB class/type code (advanced)",
                        "type": "string",
                        "description": "Exact 3-digit TTB class/type code (e.g. `101` = Straight Bourbon Whisky). Overrides `productCategory` when set. Full code list: ttbonline.gov COLAs Online > Advanced Search > Lookup Class Type."
                    },
                    "originCode": {
                        "title": "Origin (US state or country)",
                        "enum": [
                            "",
                            "ZY",
                            "10",
                            "4E",
                            "60",
                            "61",
                            "00",
                            "7Q",
                            "4Y",
                            "62",
                            "11",
                            "12",
                            "6A",
                            "4P",
                            "63",
                            "64",
                            "6B",
                            "4G",
                            "4H",
                            "6C",
                            "65",
                            "7D",
                            "8K",
                            "4C",
                            "9I",
                            "66",
                            "8E",
                            "9U",
                            "67",
                            "68",
                            "9B",
                            "4X",
                            "01",
                            "4N",
                            "7L",
                            "69",
                            "9A",
                            "70",
                            "96",
                            "71",
                            "13",
                            "14",
                            "6Z",
                            "6Y",
                            "4I",
                            "72",
                            "5Y",
                            "73",
                            "15",
                            "9C",
                            "55",
                            "4K",
                            "DO",
                            "4D",
                            "7A",
                            "98",
                            "74",
                            "5A",
                            "6P",
                            "4M",
                            "6D",
                            "9S",
                            "5Q",
                            "FI",
                            "4W",
                            "97",
                            "16",
                            "51",
                            "9G",
                            "08",
                            "6E",
                            "53",
                            "7H",
                            "4U",
                            "57",
                            "5T",
                            "7R",
                            "9Q",
                            "5M",
                            "9K",
                            "5P",
                            "5N",
                            "17",
                            "6U",
                            "5L",
                            "75",
                            "5H",
                            "18",
                            "04",
                            "5I",
                            "19",
                            "7B",
                            "20",
                            "9T",
                            "5E",
                            "56",
                            "50",
                            "5W",
                            "5J",
                            "59",
                            "77",
                            "21",
                            "6F",
                            "22",
                            "4J",
                            "4L",
                            "6G",
                            "8C",
                            "6H",
                            "5F",
                            "78",
                            "8L",
                            "6I",
                            "23",
                            "79",
                            "9E",
                            "24",
                            "9M",
                            "80",
                            "7F",
                            "25",
                            "26",
                            "8H",
                            "81",
                            "06",
                            "27",
                            "28",
                            "29",
                            "6J",
                            "3A",
                            "7Y",
                            "30",
                            "9N",
                            "82",
                            "MC",
                            "7Z",
                            "8D",
                            "31",
                            "7V",
                            "83",
                            "32",
                            "33",
                            "03",
                            "34",
                            "02",
                            "84",
                            "4F",
                            "5V",
                            "35",
                            "36",
                            "7G",
                            "6W",
                            "5C",
                            "09",
                            "37",
                            "38",
                            "6V",
                            "9P",
                            "7E",
                            "8F",
                            "39",
                            "85",
                            "5S",
                            "99",
                            "54",
                            "4A",
                            "7C",
                            "8M",
                            "9R",
                            "7X",
                            "40",
                            "86",
                            "RW",
                            "7W",
                            "7M",
                            "9H",
                            "6T",
                            "5K",
                            "9D",
                            "7P",
                            "8N",
                            "5R",
                            "8I",
                            "5O",
                            "6X",
                            "7J",
                            "91",
                            "41",
                            "42",
                            "5D",
                            "52",
                            "7U",
                            "3B",
                            "8B",
                            "9F",
                            "5B",
                            "87",
                            "SY",
                            "4V",
                            "8A",
                            "6L",
                            "4R",
                            "43",
                            "44",
                            "5G",
                            "6R",
                            "6S",
                            "4Z",
                            "TZ",
                            "7K",
                            "89",
                            "90",
                            "6M",
                            "4S",
                            "6N",
                            "92",
                            "93",
                            "45",
                            "6O",
                            "95",
                            "46",
                            "5Z",
                            "4B",
                            "05",
                            "6Q",
                            "07",
                            "8J",
                            "7T",
                            "47",
                            "48",
                            "49",
                            "58",
                            "8G",
                            "5U"
                        ],
                        "type": "string",
                        "description": "Restrict results to labels originating from a specific US state or country.",
                        "default": ""
                    },
                    "permitId": {
                        "title": "Plant registry / basic permit number",
                        "type": "string",
                        "description": "Restrict results to a specific producer's permit/plant number (e.g. `DSP-CO-20073`)."
                    },
                    "vendorCode": {
                        "title": "Vendor code",
                        "type": "string",
                        "description": "Restrict results to a specific TTB vendor code."
                    },
                    "ttbIdFrom": {
                        "title": "TTB ID range — from",
                        "type": "string",
                        "description": "Lower bound of a TTB ID range (14-digit COLA identifier)."
                    },
                    "ttbIdTo": {
                        "title": "TTB ID range — to",
                        "type": "string",
                        "description": "Upper bound of a TTB ID range."
                    },
                    "serialNumFrom": {
                        "title": "Serial number range — from",
                        "type": "string",
                        "description": "Lower bound of the applicant's internal serial-number range."
                    },
                    "serialNumTo": {
                        "title": "Serial number range — to",
                        "type": "string",
                        "description": "Upper bound of the applicant's internal serial-number range."
                    },
                    "statusFilter": {
                        "title": "COLA status",
                        "enum": [
                            "",
                            "APPROVED",
                            "DENIED",
                            "SURRENDERED/REVOKED"
                        ],
                        "type": "string",
                        "description": "Only emit COLAs with this status (client-side filter, applied after fetching detail data).",
                        "default": ""
                    },
                    "ttbIds": {
                        "title": "TTB IDs (mode=byTtbId)",
                        "type": "array",
                        "description": "One or more 14-digit TTB IDs to fetch directly, e.g. `24159001000118`.",
                        "default": [],
                        "items": {
                            "type": "string"
                        }
                    },
                    "includeApplicantDetails": {
                        "title": "Include applicant/detail fields",
                        "type": "boolean",
                        "description": "Fetch each COLA's detail page for status, applicant name/address, contact info, formula, and qualifications. Adds one extra request per record.",
                        "default": true
                    },
                    "includeLabelImages": {
                        "title": "Include label images",
                        "type": "boolean",
                        "description": "Fetch each COLA's approved label image(s) and re-host them in this run's key-value store. Adds one extra request per record plus one per image.",
                        "default": true
                    },
                    "maxItems": {
                        "title": "Max items",
                        "minimum": 1,
                        "maximum": 1000,
                        "type": "integer",
                        "description": "Hard cap on emitted records. TTB's own search results window shows at most 1000 matches per query.",
                        "default": 20
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
