TTB COLA Registry Scraper: 27 Data Fields per Record (2026)

Each record carries 27 output fields, including the applicant name, formula, basic permit, and re-hosted label artwork. A thousand results cost $5.00 on the free-plan price, and the platform free tier fully covers this volume. Compliance officers and trade analysts can export verified Certificate of Label Approval data directly from the public registry without a login or session tokens. This scraper is designed for trade compliance, product verification, and market analysis; it is not for users who need consumer retail pricing or active stock availability, which the public registry does not track.

Try it: open TTB COLA Registry Scraper on Apify, sign in on the free plan and run the prefilled example.

Can you try TTB COLA Registry Scraper before paying?

Yes. Apify's free plan includes $5.00 of prepaid usage every month and asks for no credit card. At $0.005 per result, that covers up to 1,000 results of TTB COLA Registry Scraper a month, before run-start charges and platform usage.

TTB COLA Registry Scraper was last updated on 2026-07-04. It is one of 1,724 Actors CrawlerBros publishes on Apify, which together have 728,503 lifetime public runs and an average rating of 4.63 out of 5 across 416 reviews.

What does it cost to run TTB COLA Registry Scraper?

Each result costs $0.005 on Apify's free plan, which is $5.00 per 1,000 results. Starting a run is charged separately at $0.005 per GB of Actor memory. Apify also bills the platform usage each run consumes, at the rates of your Apify plan, on top of these charges.

The result cap is the key controller of your run cost because you are billed per result written to the dataset. To manage expenses, use a targeted dateCompletedFrom and dateCompletedTo range to avoid writing unwanted historical matches. While includeLabelImages is useful, disabling it prevents extra platform resource consumption when artwork binaries are not needed.

How do you run TTB COLA Registry Scraper from the API?

The schema marks 1 of its 19 controls as required: mode. Every value in the payload below comes from the published schema's own prefills, which means you can paste it, swap the token, and get a real result.

Call the synchronous endpoint to start a run and receive dataset items in one request:

curl -X POST "https://api.apify.com/v2/acts/crawlerbros~ttb-cola-registry-scraper/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"search"}'

The same run from Python, using the official client:

from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")

run_input = {
  "mode": "search"
}

run = client.actor("crawlerbros~ttb-cola-registry-scraper").call(run_input=run_input)

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

And from Node.js:

import { ApifyClient } from 'apify-client'

const client = new ApifyClient({ token: '<YOUR_APIFY_TOKEN>' })

const input = {
  "mode": "search"
}

const run = await client.actor('crawlerbros~ttb-cola-registry-scraper').call(input)
const { items } = await client.dataset(run.defaultDatasetId).listItems()
console.log(items)

That endpoint blocks until the run completes. Fine while you are testing a handful of records, risky once a run takes minutes: a dropped connection loses the response even though the run itself finished. Switch to an asynchronous start with polling or a webhook before you schedule anything.

Which TTB COLA Registry Scraper inputs matter, and which can you skip?

The mode parameter dictates whether you run a broad registry search or a direct, pinpoint lookup. Most practitioners should start in search mode with a defined date range, leaving classTypeCode and originCode blank until they need to isolate specific spirits classes or states.

• mode (string): What to fetch. Default: "search".
• productOrFancifulName (string): 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 (string): Which name field productOrFancifulName should match. Default: "E".
• dateCompletedFrom (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. Default: "01/01/2015".
• dateCompletedTo (string): End of the COLA completion-date range (<= 15 years after dateCompletedFrom). Default: "12/31/2024".
• productCategory (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. Default: "".
• classTypeCode (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 (string): Restrict results to labels originating from a specific US state or country. Default: "".
• permitId (string): Restrict results to a specific producer's permit/plant number (e.g. DSP-CO-20073).
• vendorCode (string): Restrict results to a specific TTB vendor code.
• ttbIdFrom (string): Lower bound of a TTB ID range (14-digit COLA identifier).
• ttbIdTo (string): Upper bound of a TTB ID range.

The other 7 controls, with their defaults, are listed in the input schema on TTB COLA Registry Scraper on Apify.

Fixed-choice controls: mode accepts search (Search COLAs), byTtbId (Lookup by TTB ID); productNameSearchType accepts E (Either (brand or fanciful)), B (Brand name only), F (Fanciful name only); productCategory accepts 13 values (default ""), including "" (Any category), WINE (still, sparkling, dessert, cider, mead), WHISKY (bourbon, rye, scotch, Irish, Canadian, malt), GIN; originCode accepts 234 values (default ""), including "" (Any origin), ZY (ADMIN CODE (ZY)), 10 (ALABAMA (10)), 4E (ALASKA (4E)).

What does TTB COLA Registry Scraper return?

The dataset is optimized for legal compliance auditing, competitor portfolio monitoring, and supply chain verification. It provides federal approval statuses, applicant details, and qualifications, but lacks commercial sales figures, regional distribution maps, or retail pricing.

• 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

These are the documented fields. Optional ones can be empty on a given record, so measure how often each field your deliverable depends on is populated across a real sample before automating the handoff.

How do you build the workflow end to end?

Open TTB COLA Registry Scraper and work through these in order. Each step ends with something to check, so a bad configuration surfaces on a small run rather than a scheduled one.

1. Select your run strategy by configuring the mode control to either search or byTtbId.
2. For search mode operations, specify your search criteria using the productOrFancifulName text field.
3. Provide a compliant search window using dateCompletedFrom and dateCompletedTo in MM/DD/YYYY format, keeping the span within 15 years.
4. Optionally filter your scope by choosing a pre-mapped beverage category under productCategory or inputting a three-digit classTypeCode.
5. Leave the optional vendorCode and permitId fields blank on your initial test run unless targeting a specific registered importer or producer.
6. Leave includeApplicantDetails and includeLabelImages as true to ensure the scrape retrieves applicantName and hosted label images.
7. Check that the maxItems cap is set to a low value under 50 to run a cheap, fast test of your parameters before retrieving larger batches.

How do you apply it? Three worked playbooks

These are TTB COLA Registry Scraper's own documented use cases, each worked through as an operating pattern rather than a description.

Use case 1: Label compliance teams

Outcome: Check whether a competitor's or your own label has an active COLA before shipping

Configure: mode = "search" productOrFancifulName = "bourbon" productNameSearchType = "E" dateCompletedFrom = "01/01/2023" dateCompletedTo = "12/31/2024" maxItems = 50

Working method: Execute the scraper using the targeted brand name and ensure includeApplicantDetails is enabled. Look up the status field in the output dataset to confirm active federal registration. Review the qualifications field to identify any specific compliance restrictions or conditional mandates attached to the approval.

Deliverable: A structured compliance dataset showing the verification status, approvalDate, and qualifications for the audited labels.

Stop condition: The returned status is SURRENDERED/REVOKED or DENIED for a label that is actively shipping to market.

Use case 2: Competitive intelligence

Outcome: Monitor new label approvals from a specific producer or permit number

Configure: mode = "search" permitId = "DSP-CO-20073" dateCompletedFrom = "01/01/2020" dateCompletedTo = "12/31/2024" maxItems = 200

Working method: Run the search with the target producer's permitId and map out the brandName and fancifulName fields. Compare the approval dates across the timeline to detect product line expansions or seasonal spirits launches. Verify packaging changes using the re-hosted artwork files.

Deliverable: A competitive portfolio log detailing every approved label, formula status, and packaging design history for the specified permit.

Stop condition: An active permit returns zero results across a multi-year query, indicating a permit number typo or system block.

Use case 3: Import/export due diligence

Outcome: Verify a foreign producer's US label approval status and formula

Configure: mode = "byTtbId" ttbIds = ["24159001000118", "17009001000001"]

Working method: Gather the 14-digit TTB IDs from the import manifest and input them into the ttbIds array. Execute the direct lookup to bypass the search index entirely. Compare the returned originCode and formula fields against the cargo's commercial bills of lading.

Deliverable: A due diligence verification report containing matching federal registry records, applicant addresses, and original label images.

Stop condition: The returned record features an originCode or formula description that contradicts the physical shipping papers.

What breaks, and how do you design around it?

The TTB search registry caps all single queries at 1,000 results. If your query exceeds this limit, partition your scrape into multiple runs with smaller calendar windows using the date controls. If label artwork fails to render, check if the record is administrative, as the scraper omits missing image fields rather than halting the run.

When should you not use TTB COLA Registry Scraper?

Do not use this scraper if you need real-time consumer retail pricing, local store inventories, or product reviews. This tool queries a federal registry, not commercial storefronts. For retail assortment tracking, wine ratings, and pricing, use ABC Fine Wine & Spirits Scraper, Saratoga Wine Exchange Scraper, Laithwaites Wine Scraper, or Master of Malt Scraper.

What should you check before trusting the output?

• Confirm that the 14-digit ttbId field contains exactly 14 numeric characters and is not null.
• Verify that the status field contains only APPROVED, DENIED, or SURRENDERED/REVOKED values.
• Check that the classTypeCode field contains a valid 3-digit TTB class or type code when retrieving spirits.
• Assert that the sourceUrl points to a valid public detail page on ttbonline.gov containing a complete applicant name.
• Validate that the labelImages array is populated with accessible hosted image URLs when includeLabelImages is enabled.

None of this proves a record is correct. It gives a scheduled TTB COLA Registry Scraper run defined points where it should stop instead of quietly passing bad data downstream.

Frequently asked questions

What is the cost per result for this scraper?

The scraper costs $0.005 per result, which is $5.00 per 1,000 results on the free tier. Apify's free plan includes $5.00 of monthly usage with no credit card, which covers up to 1,000 results of this Actor before standard platform charges are added.

Why does the scraper require a completed date range?

The TTB public registry mandates a date range for every search query to prevent database strain. The search engine rejects any span greater than 15 years. The scraper automatically validates and clamps input ranges to ensure your run does not fail.

Can I lookup specific labels directly if I have their identifiers?

Yes. Switch the mode parameter to byTtbId and provide the 14-digit identifiers in the ttbIds array. This bypasses the registry search index and goes straight to the individual detail pages, saving processing time.

Why are some label images missing from the scraped dataset?

Not every filing contains digital artwork. Older historical records or purely administrative changes may not have images uploaded. The scraper omits missing image fields to prevent broken URLs in your data.

What is the maximum number of records I can fetch in a search?

The TTB registry caps all public search results at 1,000 matches. Even if more matches exist, the registry will not display them. To fetch more records, split your runs into narrow date completed increments.

Where to go next

When you are ready to run it, open TTB COLA Registry Scraper on Apify; the free plan covers up to 1,000 results a month.

Other Actors we maintain for related data:

• ABC Fine Wine & Spirits Scraper: Scrape ABC Fine Wine & Spirits (abcfws.com).
• Saratoga Wine Exchange Scraper: Scrape SaratogaWine.com - a major US wine, spirits and beer retailer with 50,000+ products.
• Laithwaites Wine Scraper: Scrape Laithwaites Wine (laithwaites.co.uk), a leading UK wine retailer.
• Master of Malt Scraper: Scrape Master of Malt's drinks marketplace - search whisky, gin, rum, vodka, beer, wine, liqueurs, brandy, champagne and sake by name, browse by category, find top-rated products, and pull full product detail with customer reviews and ratings.
• FDA Medical Device Establishment Registry Scraper: Search the FDA's public Medical Device Establishment Registration & Listing database (openFDA) by establishment/business name, owner-operator firm, device name, state, or country.
• Norway Brønnøysund Company Registry Scraper: Search Norway's official Brønnøysund Register Centre (Enhetsregisteret) for registered companies and organisations by name or exact organisation number.
• NPI Provider Registry Scraper: Search the CMS National Provider Identifier (NPI) registry for US healthcare providers - doctors, hospitals, nurses, and other licensed professionals.
• NPPES NPI Registry Scraper: Scrape the US National Plan and Provider Enumeration System (NPPES) NPI Registry - the official federal database of 7M+ healthcare providers.

Related guides:

• Master of Malt Scraper: $5.00 per 1,000 results (2026)
• NYC DOB Permits & Violations Scraper: Up to 1,000 Free Results a Month
• Open Food Facts Scraper: 37 Data Fields per Record (2026)
• Ausbildung.de Vocational Training Scraper: 3 Practical Use Cases

Resources

• Actor documentation, input schema, and pricing: verified against the published Actor on 2026-10-04.

• Actor last updated by its maintainers on 2026-07-04.

• Run outcome figures cover the 30 day public window ending 2026-10-04.

• TTB COLA Registry Scraper on Apify