---
title: "Search COLAs"
method: GET
path: "/colas"
tags: ["COLAs"]
---

# Search COLAs

`GET /colas`

## Request

- Base URL: `https://app.colacloud.us/api/v1`
- URL: `https://app.colacloud.us/api/v1/colas`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Search and filter Certificates of Label Approval with full-text search and various filters.
Results are ordered by approval date (descending).

When no explicit date filters (`approval_date_from`, `approval_date_to`) are provided, results
default to the last 365 days, except for exact 14-digit TTB-ID searches and non-approved
status filters (`expired`, `surrendered`, or `revoked`), which search all available history.
Explicit date filters always take precedence. The `defaults_applied` field in the response
indicates when the recent-date default is active.

## Query parameters

- `q` string
- `product_type` string[]
- `category` string[]
- `derived_subcategory` string
- `origin` string
- `domestic_or_imported` 'domestic' | 'imported'
- `status` 'approved' | 'expired' | 'surrendered' | 'revoked'
- `brand_name` string
- `permit_number` string
- `barcode_value` string
- `approval_date_from` string, date
- `approval_date_to` string, date
- `abv_min` number, float
- `abv_max` number, float
- `volume_unit` 'beer barrels' | 'fluid ounces' | 'gallons' | 'liters' | 'milliliters' | 'pints' | 'quarts'
- `volume_min` number, float
- `volume_max` number, float
- `container_type` string[]
- `product_style` string[]
- `product_base` string[]
- `page` integer
- `per_page` integer

## Response `200`

Successful response

- object
  - `data` ColaSummary[]
    - `ttb_id` string: Unique TTB identifier
    - `brand_name` string: Brand name on the label
    - `product_name` string: Product name
    - `product_type` 'wine' | 'malt beverage' | 'distilled spirits': Type of alcohol product
    - `class_name` string: TTB classification (e.g., "table red wine")
    - `origin_name` string: Country/region of origin
    - `applicant_trade_name` string, nullable: Applicant DBA/trade name explicitly marked "Used on label" in the captured COLA form, preserving source spelling. Separate from legal company and product brand. Null means no unambiguous marked value was captured, not that the applicant has no trade name.
    - `permit_number` string: Permit number of the producer/importer
    - `application_status` 'approved' | 'expired' | 'surrendered' | 'revoked', nullable: Current application status published by TTB
    - `approval_date` string, date, nullable
    - `image_count` integer: Number of label images
    - `has_barcode` boolean: Whether any barcode was extracted from label images
  - `pagination` Pagination
    - `mode` 'offset' | 'cursor': Pagination mode
    - `page` integer: Current page number (offset mode only)
    - `per_page` integer: Results per page
    - `total` integer, nullable: Total number of results (null in offset mode)
    - `pages` integer, nullable: Total number of pages (null in offset mode)
    - `has_more` boolean: Whether more results are available
    - `next_cursor` string, nullable: Cursor for next page (cursor mode only)

## Other responses

- `401`: Missing or invalid API key or Bearer token
- `429`: Quota or burst limit exceeded

---

[API](https://skmtc.dev/colacloud/apis/cola-cloud-api.md) · [All operations](https://skmtc.dev/colacloud/apis/cola-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/colacloud/apis/cola-cloud-api/revisions/1cb00a02112c?raw)