Lookup

The lookup endpoint resolves free-form input — a brand name, a domain, a full URL, or a @handle from Instagram or TikTok — to a list of matching brand records. Use it before calling any of the brand or ads endpoints when all you have is a name or a handle.

Free to call. This endpoint is unmetered — it does not count against your daily or monthly quota and charges no credits. Responses include X-Quota-Charged: false.

GET/v1/lookup

Resolve an identifier

Required attributes

Name
q
Type
string
Description
Free-form identifier. Examples: "Allbirds", "allbirds.com", "https://www.allbirds.com", "@allbirds". Length 1-255.

Optional attributes

Name
type
Type
string
Description
Resolution hint. Default auto — detects from the shape of q (e.g., @xxx → handle, xxx.yyy → domain). Override with one of: domain, instagram_handle, tiktok_handle, name.
Name
limit
Type
integer
Description
Maximum number of matches to return (1-10, default 5).

Response

Name
query
Type
string
Description
The original q input, echoed back.
Name
type_used
Type
string
Description
Which resolution strategy was actually applied (e.g., domain, instagram_handle, name).
Name
matches
Type
array
Description
Up to limit brand records. Each match contains the brand's default fields plus a match_signal describing how it matched (e.g., domain_exact, instagram_handle_match, name_match).

Request

GET

/v1/lookup

curl -G https://api.brandsearch.co/v1/lookup \
  -H "X-API-Key: bsk_your_api_key" \
  -d q=allbirds.com

Response

{
  "query": "allbirds.com",
  "type_used": "domain",
  "matches": [
    {
      "id": "allbirds.com",
      "name": "Allbirds",
      "title": "Allbirds — Comfortable, Sustainable Shoes",
      "description": "Shop natural materials. Trusted by millions.",
      "monthly_visits": 4200000,
      "niche": "Fashion",
      "country_code": "US",
      "match_signal": "domain_exact"
    }
  ]
}

POST/v1/lookup

Batch resolve

Resolve up to 50 identifiers in a single request. Same per-query rules as the GET form, results returned in input order. Still unmetered — zero cost.

Body

Name
queries
Type
array
Description
Array of {q, type?, limit?} objects. Each entry uses the same rules as the GET endpoint. Cap of 50 entries per call.

Response

Name
results
Type
array
Description
Array of lookup responses (same shape as GET /v1/lookup), one per input query in the same order.

Request

POST

/v1/lookup

curl -X POST https://api.brandsearch.co/v1/lookup \
  -H "X-API-Key: bsk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {"q": "allbirds.com"},
      {"q": "@nike", "type": "instagram_handle"},
      {"q": "Patagonia", "type": "name", "limit": 3}
    ]
  }'

Response

{
  "results": [
    {
      "query": "allbirds.com",
      "type_used": "domain",
      "matches": [{ "id": "allbirds.com", "name": "Allbirds", "match_signal": "domain_exact" }]
    },
    {
      "query": "@nike",
      "type_used": "instagram_handle",
      "matches": [{ "id": "nike.com", "name": "Nike", "match_signal": "instagram_handle_match" }]
    },
    {
      "query": "Patagonia",
      "type_used": "name",
      "matches": [
        { "id": "patagonia.com", "name": "Patagonia", "match_signal": "name_match" }
      ]
    }
  ]
}